diff --git a/src/.vuepress/sidebar/V1.3.x/en.ts b/src/.vuepress/sidebar/V1.3.x/en.ts index fe171bdeb..b8f33477d 100644 --- a/src/.vuepress/sidebar/V1.3.x/en.ts +++ b/src/.vuepress/sidebar/V1.3.x/en.ts @@ -149,7 +149,7 @@ export const enSidebar = { prefix: 'Tools-System/', // children: 'structure', children: [ - { text: 'Command Line Interface (CLI)', link: 'CLI' }, + { text: 'Command Line Interface (CLI)', link: 'CLI_apache' }, { text: 'Monitor Tool', link: 'Monitor-Tool_apache' }, { text: 'Benchmark Tool', link: 'Benchmark' }, { text: 'Cluster Management Tool', link: 'Maintenance-Tool_apache' }, diff --git a/src/.vuepress/sidebar/V1.3.x/zh.ts b/src/.vuepress/sidebar/V1.3.x/zh.ts index 7370c44c9..f94b41bcc 100644 --- a/src/.vuepress/sidebar/V1.3.x/zh.ts +++ b/src/.vuepress/sidebar/V1.3.x/zh.ts @@ -138,7 +138,7 @@ export const zhSidebar = { prefix: 'Tools-System/', // children: 'structure', children: [ - { text: '命令行工具', link: 'CLI' }, + { text: '命令行工具', link: 'CLI_apache' }, { text: '监控工具', link: 'Monitor-Tool_apache' }, { text: '测试工具', link: 'Benchmark' }, { text: '集群管理工具', link: 'Maintenance-Tool_apache' }, diff --git a/src/.vuepress/sidebar/V2.0.x/en-Tree.ts b/src/.vuepress/sidebar/V2.0.x/en-Tree.ts index f2bc7aa80..1047e8bd9 100644 --- a/src/.vuepress/sidebar/V2.0.x/en-Tree.ts +++ b/src/.vuepress/sidebar/V2.0.x/en-Tree.ts @@ -139,7 +139,7 @@ export const enSidebar = { collapsible: true, prefix: 'Tools-System/', children: [ - { text: 'Command Line Interface (CLI)', link: 'CLI' }, + { text: 'Command Line Interface (CLI)', link: 'CLI_apache' }, { text: 'Monitor Tool', link: 'Monitor-Tool_apache' }, { text: 'Benchmark Tool', link: 'Benchmark' }, { text: 'Cluster Management Tool', link: 'Maintenance-Tool_apache' }, diff --git a/src/.vuepress/sidebar/V2.0.x/zh-Tree.ts b/src/.vuepress/sidebar/V2.0.x/zh-Tree.ts index 362e1c4fb..2c583e8e8 100644 --- a/src/.vuepress/sidebar/V2.0.x/zh-Tree.ts +++ b/src/.vuepress/sidebar/V2.0.x/zh-Tree.ts @@ -128,7 +128,7 @@ export const zhSidebar = { collapsible: true, prefix: 'Tools-System/', children: [ - { text: '命令行工具', link: 'CLI' }, + { text: '命令行工具', link: 'CLI_apache' }, { text: '监控工具', link: 'Monitor-Tool_apache' }, { text: '测试工具', link: 'Benchmark' }, { text: '集群管理工具', link: 'Maintenance-Tool_apache' }, diff --git a/src/.vuepress/sidebar_timecho/V1.3.x/en.ts b/src/.vuepress/sidebar_timecho/V1.3.x/en.ts index 6920a148d..762901b5b 100644 --- a/src/.vuepress/sidebar_timecho/V1.3.x/en.ts +++ b/src/.vuepress/sidebar_timecho/V1.3.x/en.ts @@ -164,7 +164,7 @@ export const enSidebar = { prefix: 'Tools-System/', // children: 'structure', children: [ - { text: 'CLI', link: 'CLI' }, + { text: 'CLI', link: 'CLI_timecho' }, { text: 'Workbench', link: 'Workbench_timecho' }, { text: 'Monitor Tool', link: 'Monitor-Tool_timecho' }, { text: 'Benchmark Tool', link: 'Benchmark' }, diff --git a/src/.vuepress/sidebar_timecho/V1.3.x/zh.ts b/src/.vuepress/sidebar_timecho/V1.3.x/zh.ts index 765c9f83e..ded8c1a1a 100644 --- a/src/.vuepress/sidebar_timecho/V1.3.x/zh.ts +++ b/src/.vuepress/sidebar_timecho/V1.3.x/zh.ts @@ -147,7 +147,7 @@ export const zhSidebar = { prefix: 'Tools-System/', // children: 'structure', children: [ - { text: '命令行工具', link: 'CLI' }, + { text: '命令行工具', link: 'CLI_timecho' }, { text: '可视化控制台', link: 'Workbench_timecho' }, { text: '监控工具', link: 'Monitor-Tool_timecho' }, { text: '测试工具', link: 'Benchmark' }, diff --git a/src/.vuepress/sidebar_timecho/V2.0.x/en-Tree.ts b/src/.vuepress/sidebar_timecho/V2.0.x/en-Tree.ts index 12b35c957..1b16b349c 100644 --- a/src/.vuepress/sidebar_timecho/V2.0.x/en-Tree.ts +++ b/src/.vuepress/sidebar_timecho/V2.0.x/en-Tree.ts @@ -154,7 +154,7 @@ export const enSidebar = { collapsible: true, prefix: 'Tools-System/', children: [ - { text: 'CLI', link: 'CLI' }, + { text: 'CLI', link: 'CLI_timecho' }, { text: 'Workbench', link: 'Workbench_timecho' }, { text: 'Monitor Tool', link: 'Monitor-Tool_timecho' }, { text: 'Benchmark Tool', link: 'Benchmark' }, diff --git a/src/.vuepress/sidebar_timecho/V2.0.x/zh-Tree.ts b/src/.vuepress/sidebar_timecho/V2.0.x/zh-Tree.ts index 092bf35a6..2d28e2d13 100644 --- a/src/.vuepress/sidebar_timecho/V2.0.x/zh-Tree.ts +++ b/src/.vuepress/sidebar_timecho/V2.0.x/zh-Tree.ts @@ -137,7 +137,7 @@ export const zhSidebar = { collapsible: true, prefix: 'Tools-System/', children: [ - { text: '命令行工具', link: 'CLI' }, + { text: '命令行工具', link: 'CLI_timecho' }, { text: '可视化控制台', link: 'Workbench_timecho' }, { text: '监控工具', link: 'Monitor-Tool_timecho' }, { text: '测试工具', link: 'Benchmark' }, diff --git a/src/UserGuide/Master/Tree/Tools-System/CLI.md b/src/UserGuide/Master/Tree/Tools-System/CLI.md index 665af2052..03580fafb 100644 --- a/src/UserGuide/Master/Tree/Tools-System/CLI.md +++ b/src/UserGuide/Master/Tree/Tools-System/CLI.md @@ -1,3 +1,6 @@ +--- +redirectTo: CLI_apache.html +--- - -# Command Line Interface (CLI) - - -IoTDB provides Cli/shell tools for users to interact with IoTDB server in command lines. This document shows how Cli/shell tool works and the meaning of its parameters. - -> Note: In this document, \$IOTDB\_HOME represents the path of the IoTDB installation directory. - -## 1. Installation - -If you use the source code version of IoTDB, then under the root path of IoTDB, execute: - -```shell -> mvn clean package -pl iotdb-client/cli -am -DskipTests -P get-jar-with-dependencies -``` - -After build, the IoTDB Cli will be in the folder "cli/target/iotdb-cli-{project.version}". - -If you download the binary version, then the Cli can be used directly in sbin folder. - -## 2. Running - -### 2.1 Running Cli - -After installation, there is a default user in IoTDB: `root`, and the -default password is `root`. Users can use this username to try IoTDB Cli/Shell tool. The cli startup script is the `start-cli` file under the \$IOTDB\_HOME/bin folder. When starting the script, you need to specify the IP and PORT. (Make sure the IoTDB cluster is running properly when you use Cli/Shell tool to connect to it.) - -Here is an example where the cluster is started locally and the user has not changed the running port. The default rpc port is -6667
-If you need to connect to the remote DataNode or changes -the rpc port number of the DataNode running, set the specific IP and RPC PORT at -h and -p.
-You also can set your own environment variable at the front of the start script - -The Linux and MacOS system startup commands are as follows: - -```shell -Shell > bash sbin/start-cli.sh -h 127.0.0.1 -p 6667 -u root -pw root -``` - -The Windows system startup commands are as follows: - -```shell -# Before version V2.0.4.x -Shell > sbin\start-cli.bat -h 127.0.0.1 -p 6667 -u root -pw root - -# V2.0.4.x and later versions -Shell > sbin\windows\start-cli.bat -h 127.0.0.1 -p 6667 -u root -pw root -``` - -After operating these commands, the cli can be started successfully. The successful status will be as follows: - -``` - _____ _________ ______ ______ -|_ _| | _ _ ||_ _ `.|_ _ \ - | | .--.|_/ | | \_| | | `. \ | |_) | - | | / .'`\ \ | | | | | | | __'. - _| |_| \__. | _| |_ _| |_.' /_| |__) | -|_____|'.__.' |_____| |______.'|_______/ version - - -Successfully login at 127.0.0.1:6667 -IoTDB> -``` - -Enter ```quit``` or `exit` can exit Cli. - -### 2.2 Cli Parameters - -| Parameter name | Parameter type | Required | Description | Example | -| :--------------------------- | :------------------------- | :------- | :----------------------------------------------------------- | :------------------ | -| -disableISO8601 | No parameters | No | If this parameter is set, IoTDB will print the timestamp in digital form | -disableISO8601 | -| -h <`host`> | string, no quotation marks | Yes | The IP address of the IoTDB server | -h 10.129.187.21 | -| -help | No parameters | No | Print help information for IoTDB | -help | -| -p <`rpcPort`> | int | Yes | The rpc port number of the IoTDB server. IoTDB runs on rpc port 6667 by default | -p 6667 | -| -pw <`password`> | string, no quotation marks | No | The password used for IoTDB to connect to the server. If no password is entered, IoTDB will ask for password in Cli command | -pw root | -| -u <`username`> | string, no quotation marks | Yes | User name used for IoTDB to connect the server | -u root | -| -maxPRC <`maxPrintRowCount`> | int | No | Set the maximum number of rows that IoTDB returns | -maxPRC 10 | -| -e <`execute`> | string | No | manipulate IoTDB in batches without entering cli input mode | -e "show databases" | -| -c | empty | No | If the server enables `rpc_thrift_compression_enable=true`, then cli must use `-c` | -c | - -Following is a cli command which connects the host with IP -10.129.187.21, rpc port 6667, username "root", password "root", and prints the timestamp in digital form. The maximum number of lines displayed on the IoTDB command line is 10. - -The Linux and MacOS system startup commands are as follows: - -```shell -Shell > bash sbin/start-cli.sh -h 10.129.187.21 -p 6667 -u root -pw root -disableISO8601 -maxPRC 10 -``` - -The Windows system startup commands are as follows: - -```shell -# Before version V2.0.4.x -Shell > sbin\start-cli.bat -h 10.129.187.21 -p 6667 -u root -pw root -disableISO8601 -maxPRC 10 - -# # V2.0.4.x and later versions -Shell > sbin\windows\start-cli.bat -h 10.129.187.21 -p 6667 -u root -pw root -disableISO8601 -maxPRC 10 -``` - -### 2.3 CLI Special Command - -Special commands of Cli are below. - -| Command | Description / Example | -| :-------------------------- | :------------------------------------------------------ | -| `set time_display_type=xxx` | eg. long, default, ISO8601, yyyy-MM-dd HH:mm:ss | -| `show time_display_type` | show time display type | -| `set time_zone=xxx` | eg. +08:00, Asia/Shanghai | -| `show time_zone` | show cli time zone | -| `set fetch_size=xxx` | set fetch size when querying data from server | -| `show fetch_size` | show fetch size | -| `set max_display_num=xxx` | set max lines for cli to output, -1 equals to unlimited | -| `help` | Get hints for CLI special commands | -| `exit/quit` | Exit CLI | - -### 2.4 Note on using the CLI with OpenID Connect Auth enabled on Server side - -Openid connect (oidc) uses keycloack as the authority authentication service of oidc service - - -#### configuration - -The configuration is located in iotdb-system.properties , set the author_provider_class is org.apache.iotdb.commons.auth.authorizer.OpenIdAuthorizer Openid service is enabled, and the default value is org.apache.iotdb.db.auth.authorizer.LocalFileAuthorizer Indicates that the openid service is not enabled. - -``` -authorizer_provider_class=org.apache.iotdb.commons.auth.authorizer.OpenIdAuthorizer -``` - -If the openid service is turned on, openid_URL is required,openID_url value is http://ip:port/realms/{realmsName} - -``` -openID_url=http://127.0.0.1:8080/realms/iotdb/ -``` - -#### keycloack configuration - -1、Download the keycloack file (This tutorial is version 21.1.0) and start keycloack in keycloack/bin - -```shell -Shell >cd bin -Shell >./kc.sh start-dev -``` - -2、use url(https://ip:port) login keycloack, the first login needs to create a user -![avatar](/img/UserGuide/CLI/Command-Line-Interface/login_keycloak.png?raw=true) - -3、Click administration console -![avatar](/img/UserGuide/CLI/Command-Line-Interface/AdministrationConsole.png?raw=true) - -4、In the master menu on the left, click Create realm and enter Realm name to create a new realm -![avatar](/img/UserGuide/CLI/Command-Line-Interface/add_Realm_1.jpg?raw=true) - -![avatar](/img/UserGuide/CLI/Command-Line-Interface/add_Realm_2.jpg?raw=true) - - -5、Click the menu clients on the left to create clients - -![avatar](/img/UserGuide/CLI/Command-Line-Interface/client.jpg?raw=true) - -6、Click user on the left menu to create user - -![avatar](/img/UserGuide/CLI/Command-Line-Interface/user.jpg?raw=true) - -7、Click the newly created user ID, click the credentials navigation, enter the password and close the temporary option. The configuration of keycloud is completed - -![avatar](/img/UserGuide/CLI/Command-Line-Interface/pwd.jpg?raw=true) - -8、To create a role, click Roles on the left menu and then click the Create Role button to add a role - -![avatar](/img/UserGuide/CLI/Command-Line-Interface/add_role1.jpg?raw=true) - -9、 Enter `iotdb_admin` in the Role Name and click the save button. Tip: `iotdb_admin` here cannot be any other name, otherwise even after successful login, you will not have permission to use iotdb's query, insert, create database, add users, roles and other functions - -![avatar](/img/UserGuide/CLI/Command-Line-Interface/add_role2.jpg?raw=true) - -10、Click on the User menu on the left and then click on the user in the user list to add the `iotdb_admin` role we just created for that user - -![avatar](/img/UserGuide/CLI/Command-Line-Interface/add_role3.jpg?raw=true) - -11、 Select Role Mappings, select the `iotdb_admin` role in Assign Role - -![avatar](/img/UserGuide/CLI/Command-Line-Interface/add_role4.jpg?raw=true) - -![avatar](/img/UserGuide/CLI/Command-Line-Interface/add_role5.jpg?raw=true) - - -Tip: If the user role is adjusted, you need to regenerate the token and log in to iotdb again to take effect - -The above steps provide a way for keycloak to log into iotdb. For more ways, please refer to keycloak configuration - -If OIDC is enabled on server side then no username / passwort is needed but a valid Access Token from the OIDC Provider. -So as username you use the token and the password has to be empty, e.g. - -```shell -Shell > bash sbin/start-cli.sh -h 10.129.187.21 -p 6667 -u {my-access-token} -pw "" -``` - -Among them, you need to replace {my access token} (note, including {}) with your token, that is, the value corresponding to access_token. The password is empty and needs to be confirmed again. - -![avatar](/img/UserGuide/CLI/Command-Line-Interface/iotdbpw.jpeg?raw=true) - - -How to get the token is dependent on your OpenID Connect setup and not covered here. -In the simplest case you can get this via the command line with the `passwort-grant`. -For example, if you use keycloack as OIDC and you have a realm with a client `iotdb` defined as public you could use -the following `curl` command to fetch a token (replace all `{}` with appropriate values). - -```shell -curl -X POST "https://{your-keycloack-server}/realms/{your-realm}/protocol/openid-connect/token" \ - -H "Content-Type: application/x-www-form-urlencoded" \ - -d "username={username}" \ - -d "password={password}" \ - -d 'grant_type=password' \ - -d "client_id=iotdb-client" -``` - -The response looks something like - -```json -{"access_token":"eyJhbGciOiJSUzI1NiIsInR5cCIgOiAiSldUIiwia2lkIiA6ICJxMS1XbTBvelE1TzBtUUg4LVNKYXAyWmNONE1tdWNXd25RV0tZeFpKNG93In0.eyJleHAiOjE1OTAzOTgwNzEsImlhdCI6MTU5MDM5Nzc3MSwianRpIjoiNjA0ZmYxMDctN2NiNy00NTRmLWIwYmQtY2M2ZDQwMjFiNGU4IiwiaXNzIjoiaHR0cDovL2F1dGguZGVtby5wcmFnbWF0aWNpbmR1c3RyaWVzLmRlL2F1dGgvcmVhbG1zL0lvVERCIiwiYXVkIjoiYWNjb3VudCIsInN1YiI6ImJhMzJlNDcxLWM3NzItNGIzMy04ZGE2LTZmZThhY2RhMDA3MyIsInR5cCI6IkJlYXJlciIsImF6cCI6ImlvdGRiIiwic2Vzc2lvbl9zdGF0ZSI6IjA2MGQyODYyLTE0ZWQtNDJmZS1iYWY3LThkMWY3ODQ2NTdmMSIsImFjciI6IjEiLCJhbGxvd2VkLW9yaWdpbnMiOlsibG9jYWxob3N0OjgwODAiXSwicmVhbG1fYWNjZXNzIjp7InJvbGVzIjpbIm9mZmxpbmVfYWNjZXNzIiwidW1hX2F1dGhvcml6YXRpb24iLCJpb3RkYl9hZG1pbiJdfSwicmVzb3VyY2VfYWNjZXNzIjp7ImFjY291bnQiOnsicm9sZXMiOlsibWFuYWdlLWFjY291bnQiLCJtYW5hZ2UtYWNjb3VudC1saW5rcyIsInZpZXctcHJvZmlsZSJdfX0sInNjb3BlIjoiZW1haWwgcHJvZmlsZSIsImVtYWlsX3ZlcmlmaWVkIjp0cnVlLCJwcmVmZXJyZWRfdXNlcm5hbWUiOiJ1c2VyIn0.nwbrJkWdCNjzFrTDwKNuV5h9dDMg5ytRKGOXmFIajpfsbOutJytjWTCB2WpA8E1YI3KM6gU6Jx7cd7u0oPo5syHhfCz119n_wBiDnyTZkFOAPsx0M2z20kvBLN9k36_VfuCMFUeddJjO31MeLTmxB0UKg2VkxdczmzMH3pnalhxqpnWWk3GnrRrhAf2sZog0foH4Ae3Ks0lYtYzaWK_Yo7E4Px42-gJpohy3JevOC44aJ4auzJR1RBj9LUbgcRinkBy0JLi6XXiYznSC2V485CSBHW3sseXn7pSXQADhnmGQrLfFGO5ZljmPO18eFJaimdjvgSChsrlSEmTDDsoo5Q","expires_in":300,"refresh_expires_in":1800,"refresh_token":"eyJhbGciOiJIUzI1NiIsInR5cCIgOiAiSldUIiwia2lkIiA6ICJhMzZlMGU0NC02MWNmLTQ5NmMtOGRlZi03NTkwNjQ5MzQzMjEifQ.eyJleHAiOjE1OTAzOTk1NzEsImlhdCI6MTU5MDM5Nzc3MSwianRpIjoiNmMxNTBiY2EtYmE5NC00NTgxLWEwODEtYjI2YzhhMmI5YmZmIiwiaXNzIjoiaHR0cDovL2F1dGguZGVtby5wcmFnbWF0aWNpbmR1c3RyaWVzLmRlL2F1dGgvcmVhbG1zL0lvVERCIiwiYXVkIjoiaHR0cDovL2F1dGguZGVtby5wcmFnbWF0aWNpbmR1c3RyaWVzLmRlL2F1dGgvcmVhbG1zL0lvVERCIiwic3ViIjoiYmEzMmU0NzEtYzc3Mi00YjMzLThkYTYtNmZlOGFjZGEwMDczIiwidHlwIjoiUmVmcmVzaCIsImF6cCI6ImlvdGRiIiwic2Vzc2lvbl9zdGF0ZSI6IjA2MGQyODYyLTE0ZWQtNDJmZS1iYWY3LThkMWY3ODQ2NTdmMSIsInNjb3BlIjoiZW1haWwgcHJvZmlsZSJ9.ayNpXdNX28qahodX1zowrMGiUCw2AodlHBQFqr8Ui7c","token_type":"bearer","not-before-policy":0,"session_state":"060d2862-14ed-42fe-baf7-8d1f784657f1","scope":"email profile"} -``` - -The interesting part here is the access token with the key `access_token`. -This has to be passed as username (with parameter `-u`) and empty password to the CLI. - -### 2.5 Batch Operation of Cli - --e parameter is designed for the Cli/shell tool in the situation where you would like to manipulate IoTDB in batches through scripts. By using the -e parameter, you can operate IoTDB without entering the cli's input mode. - -In order to avoid confusion between statements and other parameters, the current version only supports the -e parameter as the last parameter. - -The usage of -e parameter for Cli/shell is as follows: - -The Linux and MacOS system commands: - -```shell -Shell > bash sbin/start-cli.sh -h {host} -p {rpcPort} -u {user} -pw {password} -e {sql for iotdb} -``` - -The Windows system commands: - -```shell -# Before version V2.0.4.x -Shell > sbin\start-cli.bat -h {host} -p {rpcPort} -u {user} -pw {password} -e {sql for iotdb} - -# V2.0.4.x and later versions -Shell > sbin\windows\start-cli.bat -h {host} -p {rpcPort} -u {user} -pw {password} -e {sql for iotdb} -``` - -In the Windows environment, the SQL statement of the -e parameter needs to use ` `` ` to replace `" "` - -In order to better explain the use of -e parameter, take following as an example(On linux system). - -Suppose you want to create a database root.demo to a newly launched IoTDB, create a timeseries root.demo.s1 and insert three data points into it. With -e parameter, you could write a shell like this: - -```shell -# !/bin/bash - -host=127.0.0.1 -rpcPort=6667 -user=root -pass=root - -bash ./sbin/start-cli.sh -h ${host} -p ${rpcPort} -u ${user} -pw ${pass} -e "create database root.demo" -bash ./sbin/start-cli.sh -h ${host} -p ${rpcPort} -u ${user} -pw ${pass} -e "create timeseries root.demo.s1 WITH DATATYPE=INT32, ENCODING=RLE" -bash ./sbin/start-cli.sh -h ${host} -p ${rpcPort} -u ${user} -pw ${pass} -e "insert into root.demo(timestamp,s1) values(1,10)" -bash ./sbin/start-cli.sh -h ${host} -p ${rpcPort} -u ${user} -pw ${pass} -e "insert into root.demo(timestamp,s1) values(2,11)" -bash ./sbin/start-cli.sh -h ${host} -p ${rpcPort} -u ${user} -pw ${pass} -e "insert into root.demo(timestamp,s1) values(3,12)" -bash ./sbin/start-cli.sh -h ${host} -p ${rpcPort} -u ${user} -pw ${pass} -e "select s1 from root.demo" -``` - -The results are shown in the figure, which are consistent with the Cli and jdbc operations. - -```shell - Shell > bash ./shell.sh -+-----------------------------+------------+ -| Time|root.demo.s1| -+-----------------------------+------------+ -|1970-01-01T08:00:00.001+08:00| 10| -|1970-01-01T08:00:00.002+08:00| 11| -|1970-01-01T08:00:00.003+08:00| 12| -+-----------------------------+------------+ -Total line number = 3 -It costs 0.267s -``` - -It should be noted that the use of the -e parameter in shell scripts requires attention to the escaping of special characters. +--> \ No newline at end of file diff --git a/src/UserGuide/Master/Tree/Tools-System/CLI_apache.md b/src/UserGuide/Master/Tree/Tools-System/CLI_apache.md new file mode 100644 index 000000000..665af2052 --- /dev/null +++ b/src/UserGuide/Master/Tree/Tools-System/CLI_apache.md @@ -0,0 +1,307 @@ + + +# Command Line Interface (CLI) + + +IoTDB provides Cli/shell tools for users to interact with IoTDB server in command lines. This document shows how Cli/shell tool works and the meaning of its parameters. + +> Note: In this document, \$IOTDB\_HOME represents the path of the IoTDB installation directory. + +## 1. Installation + +If you use the source code version of IoTDB, then under the root path of IoTDB, execute: + +```shell +> mvn clean package -pl iotdb-client/cli -am -DskipTests -P get-jar-with-dependencies +``` + +After build, the IoTDB Cli will be in the folder "cli/target/iotdb-cli-{project.version}". + +If you download the binary version, then the Cli can be used directly in sbin folder. + +## 2. Running + +### 2.1 Running Cli + +After installation, there is a default user in IoTDB: `root`, and the +default password is `root`. Users can use this username to try IoTDB Cli/Shell tool. The cli startup script is the `start-cli` file under the \$IOTDB\_HOME/bin folder. When starting the script, you need to specify the IP and PORT. (Make sure the IoTDB cluster is running properly when you use Cli/Shell tool to connect to it.) + +Here is an example where the cluster is started locally and the user has not changed the running port. The default rpc port is +6667
+If you need to connect to the remote DataNode or changes +the rpc port number of the DataNode running, set the specific IP and RPC PORT at -h and -p.
+You also can set your own environment variable at the front of the start script + +The Linux and MacOS system startup commands are as follows: + +```shell +Shell > bash sbin/start-cli.sh -h 127.0.0.1 -p 6667 -u root -pw root +``` + +The Windows system startup commands are as follows: + +```shell +# Before version V2.0.4.x +Shell > sbin\start-cli.bat -h 127.0.0.1 -p 6667 -u root -pw root + +# V2.0.4.x and later versions +Shell > sbin\windows\start-cli.bat -h 127.0.0.1 -p 6667 -u root -pw root +``` + +After operating these commands, the cli can be started successfully. The successful status will be as follows: + +``` + _____ _________ ______ ______ +|_ _| | _ _ ||_ _ `.|_ _ \ + | | .--.|_/ | | \_| | | `. \ | |_) | + | | / .'`\ \ | | | | | | | __'. + _| |_| \__. | _| |_ _| |_.' /_| |__) | +|_____|'.__.' |_____| |______.'|_______/ version + + +Successfully login at 127.0.0.1:6667 +IoTDB> +``` + +Enter ```quit``` or `exit` can exit Cli. + +### 2.2 Cli Parameters + +| Parameter name | Parameter type | Required | Description | Example | +| :--------------------------- | :------------------------- | :------- | :----------------------------------------------------------- | :------------------ | +| -disableISO8601 | No parameters | No | If this parameter is set, IoTDB will print the timestamp in digital form | -disableISO8601 | +| -h <`host`> | string, no quotation marks | Yes | The IP address of the IoTDB server | -h 10.129.187.21 | +| -help | No parameters | No | Print help information for IoTDB | -help | +| -p <`rpcPort`> | int | Yes | The rpc port number of the IoTDB server. IoTDB runs on rpc port 6667 by default | -p 6667 | +| -pw <`password`> | string, no quotation marks | No | The password used for IoTDB to connect to the server. If no password is entered, IoTDB will ask for password in Cli command | -pw root | +| -u <`username`> | string, no quotation marks | Yes | User name used for IoTDB to connect the server | -u root | +| -maxPRC <`maxPrintRowCount`> | int | No | Set the maximum number of rows that IoTDB returns | -maxPRC 10 | +| -e <`execute`> | string | No | manipulate IoTDB in batches without entering cli input mode | -e "show databases" | +| -c | empty | No | If the server enables `rpc_thrift_compression_enable=true`, then cli must use `-c` | -c | + +Following is a cli command which connects the host with IP +10.129.187.21, rpc port 6667, username "root", password "root", and prints the timestamp in digital form. The maximum number of lines displayed on the IoTDB command line is 10. + +The Linux and MacOS system startup commands are as follows: + +```shell +Shell > bash sbin/start-cli.sh -h 10.129.187.21 -p 6667 -u root -pw root -disableISO8601 -maxPRC 10 +``` + +The Windows system startup commands are as follows: + +```shell +# Before version V2.0.4.x +Shell > sbin\start-cli.bat -h 10.129.187.21 -p 6667 -u root -pw root -disableISO8601 -maxPRC 10 + +# # V2.0.4.x and later versions +Shell > sbin\windows\start-cli.bat -h 10.129.187.21 -p 6667 -u root -pw root -disableISO8601 -maxPRC 10 +``` + +### 2.3 CLI Special Command + +Special commands of Cli are below. + +| Command | Description / Example | +| :-------------------------- | :------------------------------------------------------ | +| `set time_display_type=xxx` | eg. long, default, ISO8601, yyyy-MM-dd HH:mm:ss | +| `show time_display_type` | show time display type | +| `set time_zone=xxx` | eg. +08:00, Asia/Shanghai | +| `show time_zone` | show cli time zone | +| `set fetch_size=xxx` | set fetch size when querying data from server | +| `show fetch_size` | show fetch size | +| `set max_display_num=xxx` | set max lines for cli to output, -1 equals to unlimited | +| `help` | Get hints for CLI special commands | +| `exit/quit` | Exit CLI | + +### 2.4 Note on using the CLI with OpenID Connect Auth enabled on Server side + +Openid connect (oidc) uses keycloack as the authority authentication service of oidc service + + +#### configuration + +The configuration is located in iotdb-system.properties , set the author_provider_class is org.apache.iotdb.commons.auth.authorizer.OpenIdAuthorizer Openid service is enabled, and the default value is org.apache.iotdb.db.auth.authorizer.LocalFileAuthorizer Indicates that the openid service is not enabled. + +``` +authorizer_provider_class=org.apache.iotdb.commons.auth.authorizer.OpenIdAuthorizer +``` + +If the openid service is turned on, openid_URL is required,openID_url value is http://ip:port/realms/{realmsName} + +``` +openID_url=http://127.0.0.1:8080/realms/iotdb/ +``` + +#### keycloack configuration + +1、Download the keycloack file (This tutorial is version 21.1.0) and start keycloack in keycloack/bin + +```shell +Shell >cd bin +Shell >./kc.sh start-dev +``` + +2、use url(https://ip:port) login keycloack, the first login needs to create a user +![avatar](/img/UserGuide/CLI/Command-Line-Interface/login_keycloak.png?raw=true) + +3、Click administration console +![avatar](/img/UserGuide/CLI/Command-Line-Interface/AdministrationConsole.png?raw=true) + +4、In the master menu on the left, click Create realm and enter Realm name to create a new realm +![avatar](/img/UserGuide/CLI/Command-Line-Interface/add_Realm_1.jpg?raw=true) + +![avatar](/img/UserGuide/CLI/Command-Line-Interface/add_Realm_2.jpg?raw=true) + + +5、Click the menu clients on the left to create clients + +![avatar](/img/UserGuide/CLI/Command-Line-Interface/client.jpg?raw=true) + +6、Click user on the left menu to create user + +![avatar](/img/UserGuide/CLI/Command-Line-Interface/user.jpg?raw=true) + +7、Click the newly created user ID, click the credentials navigation, enter the password and close the temporary option. The configuration of keycloud is completed + +![avatar](/img/UserGuide/CLI/Command-Line-Interface/pwd.jpg?raw=true) + +8、To create a role, click Roles on the left menu and then click the Create Role button to add a role + +![avatar](/img/UserGuide/CLI/Command-Line-Interface/add_role1.jpg?raw=true) + +9、 Enter `iotdb_admin` in the Role Name and click the save button. Tip: `iotdb_admin` here cannot be any other name, otherwise even after successful login, you will not have permission to use iotdb's query, insert, create database, add users, roles and other functions + +![avatar](/img/UserGuide/CLI/Command-Line-Interface/add_role2.jpg?raw=true) + +10、Click on the User menu on the left and then click on the user in the user list to add the `iotdb_admin` role we just created for that user + +![avatar](/img/UserGuide/CLI/Command-Line-Interface/add_role3.jpg?raw=true) + +11、 Select Role Mappings, select the `iotdb_admin` role in Assign Role + +![avatar](/img/UserGuide/CLI/Command-Line-Interface/add_role4.jpg?raw=true) + +![avatar](/img/UserGuide/CLI/Command-Line-Interface/add_role5.jpg?raw=true) + + +Tip: If the user role is adjusted, you need to regenerate the token and log in to iotdb again to take effect + +The above steps provide a way for keycloak to log into iotdb. For more ways, please refer to keycloak configuration + +If OIDC is enabled on server side then no username / passwort is needed but a valid Access Token from the OIDC Provider. +So as username you use the token and the password has to be empty, e.g. + +```shell +Shell > bash sbin/start-cli.sh -h 10.129.187.21 -p 6667 -u {my-access-token} -pw "" +``` + +Among them, you need to replace {my access token} (note, including {}) with your token, that is, the value corresponding to access_token. The password is empty and needs to be confirmed again. + +![avatar](/img/UserGuide/CLI/Command-Line-Interface/iotdbpw.jpeg?raw=true) + + +How to get the token is dependent on your OpenID Connect setup and not covered here. +In the simplest case you can get this via the command line with the `passwort-grant`. +For example, if you use keycloack as OIDC and you have a realm with a client `iotdb` defined as public you could use +the following `curl` command to fetch a token (replace all `{}` with appropriate values). + +```shell +curl -X POST "https://{your-keycloack-server}/realms/{your-realm}/protocol/openid-connect/token" \ + -H "Content-Type: application/x-www-form-urlencoded" \ + -d "username={username}" \ + -d "password={password}" \ + -d 'grant_type=password' \ + -d "client_id=iotdb-client" +``` + +The response looks something like + +```json +{"access_token":"eyJhbGciOiJSUzI1NiIsInR5cCIgOiAiSldUIiwia2lkIiA6ICJxMS1XbTBvelE1TzBtUUg4LVNKYXAyWmNONE1tdWNXd25RV0tZeFpKNG93In0.eyJleHAiOjE1OTAzOTgwNzEsImlhdCI6MTU5MDM5Nzc3MSwianRpIjoiNjA0ZmYxMDctN2NiNy00NTRmLWIwYmQtY2M2ZDQwMjFiNGU4IiwiaXNzIjoiaHR0cDovL2F1dGguZGVtby5wcmFnbWF0aWNpbmR1c3RyaWVzLmRlL2F1dGgvcmVhbG1zL0lvVERCIiwiYXVkIjoiYWNjb3VudCIsInN1YiI6ImJhMzJlNDcxLWM3NzItNGIzMy04ZGE2LTZmZThhY2RhMDA3MyIsInR5cCI6IkJlYXJlciIsImF6cCI6ImlvdGRiIiwic2Vzc2lvbl9zdGF0ZSI6IjA2MGQyODYyLTE0ZWQtNDJmZS1iYWY3LThkMWY3ODQ2NTdmMSIsImFjciI6IjEiLCJhbGxvd2VkLW9yaWdpbnMiOlsibG9jYWxob3N0OjgwODAiXSwicmVhbG1fYWNjZXNzIjp7InJvbGVzIjpbIm9mZmxpbmVfYWNjZXNzIiwidW1hX2F1dGhvcml6YXRpb24iLCJpb3RkYl9hZG1pbiJdfSwicmVzb3VyY2VfYWNjZXNzIjp7ImFjY291bnQiOnsicm9sZXMiOlsibWFuYWdlLWFjY291bnQiLCJtYW5hZ2UtYWNjb3VudC1saW5rcyIsInZpZXctcHJvZmlsZSJdfX0sInNjb3BlIjoiZW1haWwgcHJvZmlsZSIsImVtYWlsX3ZlcmlmaWVkIjp0cnVlLCJwcmVmZXJyZWRfdXNlcm5hbWUiOiJ1c2VyIn0.nwbrJkWdCNjzFrTDwKNuV5h9dDMg5ytRKGOXmFIajpfsbOutJytjWTCB2WpA8E1YI3KM6gU6Jx7cd7u0oPo5syHhfCz119n_wBiDnyTZkFOAPsx0M2z20kvBLN9k36_VfuCMFUeddJjO31MeLTmxB0UKg2VkxdczmzMH3pnalhxqpnWWk3GnrRrhAf2sZog0foH4Ae3Ks0lYtYzaWK_Yo7E4Px42-gJpohy3JevOC44aJ4auzJR1RBj9LUbgcRinkBy0JLi6XXiYznSC2V485CSBHW3sseXn7pSXQADhnmGQrLfFGO5ZljmPO18eFJaimdjvgSChsrlSEmTDDsoo5Q","expires_in":300,"refresh_expires_in":1800,"refresh_token":"eyJhbGciOiJIUzI1NiIsInR5cCIgOiAiSldUIiwia2lkIiA6ICJhMzZlMGU0NC02MWNmLTQ5NmMtOGRlZi03NTkwNjQ5MzQzMjEifQ.eyJleHAiOjE1OTAzOTk1NzEsImlhdCI6MTU5MDM5Nzc3MSwianRpIjoiNmMxNTBiY2EtYmE5NC00NTgxLWEwODEtYjI2YzhhMmI5YmZmIiwiaXNzIjoiaHR0cDovL2F1dGguZGVtby5wcmFnbWF0aWNpbmR1c3RyaWVzLmRlL2F1dGgvcmVhbG1zL0lvVERCIiwiYXVkIjoiaHR0cDovL2F1dGguZGVtby5wcmFnbWF0aWNpbmR1c3RyaWVzLmRlL2F1dGgvcmVhbG1zL0lvVERCIiwic3ViIjoiYmEzMmU0NzEtYzc3Mi00YjMzLThkYTYtNmZlOGFjZGEwMDczIiwidHlwIjoiUmVmcmVzaCIsImF6cCI6ImlvdGRiIiwic2Vzc2lvbl9zdGF0ZSI6IjA2MGQyODYyLTE0ZWQtNDJmZS1iYWY3LThkMWY3ODQ2NTdmMSIsInNjb3BlIjoiZW1haWwgcHJvZmlsZSJ9.ayNpXdNX28qahodX1zowrMGiUCw2AodlHBQFqr8Ui7c","token_type":"bearer","not-before-policy":0,"session_state":"060d2862-14ed-42fe-baf7-8d1f784657f1","scope":"email profile"} +``` + +The interesting part here is the access token with the key `access_token`. +This has to be passed as username (with parameter `-u`) and empty password to the CLI. + +### 2.5 Batch Operation of Cli + +-e parameter is designed for the Cli/shell tool in the situation where you would like to manipulate IoTDB in batches through scripts. By using the -e parameter, you can operate IoTDB without entering the cli's input mode. + +In order to avoid confusion between statements and other parameters, the current version only supports the -e parameter as the last parameter. + +The usage of -e parameter for Cli/shell is as follows: + +The Linux and MacOS system commands: + +```shell +Shell > bash sbin/start-cli.sh -h {host} -p {rpcPort} -u {user} -pw {password} -e {sql for iotdb} +``` + +The Windows system commands: + +```shell +# Before version V2.0.4.x +Shell > sbin\start-cli.bat -h {host} -p {rpcPort} -u {user} -pw {password} -e {sql for iotdb} + +# V2.0.4.x and later versions +Shell > sbin\windows\start-cli.bat -h {host} -p {rpcPort} -u {user} -pw {password} -e {sql for iotdb} +``` + +In the Windows environment, the SQL statement of the -e parameter needs to use ` `` ` to replace `" "` + +In order to better explain the use of -e parameter, take following as an example(On linux system). + +Suppose you want to create a database root.demo to a newly launched IoTDB, create a timeseries root.demo.s1 and insert three data points into it. With -e parameter, you could write a shell like this: + +```shell +# !/bin/bash + +host=127.0.0.1 +rpcPort=6667 +user=root +pass=root + +bash ./sbin/start-cli.sh -h ${host} -p ${rpcPort} -u ${user} -pw ${pass} -e "create database root.demo" +bash ./sbin/start-cli.sh -h ${host} -p ${rpcPort} -u ${user} -pw ${pass} -e "create timeseries root.demo.s1 WITH DATATYPE=INT32, ENCODING=RLE" +bash ./sbin/start-cli.sh -h ${host} -p ${rpcPort} -u ${user} -pw ${pass} -e "insert into root.demo(timestamp,s1) values(1,10)" +bash ./sbin/start-cli.sh -h ${host} -p ${rpcPort} -u ${user} -pw ${pass} -e "insert into root.demo(timestamp,s1) values(2,11)" +bash ./sbin/start-cli.sh -h ${host} -p ${rpcPort} -u ${user} -pw ${pass} -e "insert into root.demo(timestamp,s1) values(3,12)" +bash ./sbin/start-cli.sh -h ${host} -p ${rpcPort} -u ${user} -pw ${pass} -e "select s1 from root.demo" +``` + +The results are shown in the figure, which are consistent with the Cli and jdbc operations. + +```shell + Shell > bash ./shell.sh ++-----------------------------+------------+ +| Time|root.demo.s1| ++-----------------------------+------------+ +|1970-01-01T08:00:00.001+08:00| 10| +|1970-01-01T08:00:00.002+08:00| 11| +|1970-01-01T08:00:00.003+08:00| 12| ++-----------------------------+------------+ +Total line number = 3 +It costs 0.267s +``` + +It should be noted that the use of the -e parameter in shell scripts requires attention to the escaping of special characters. diff --git a/src/UserGuide/Master/Tree/Tools-System/CLI_timecho.md b/src/UserGuide/Master/Tree/Tools-System/CLI_timecho.md new file mode 100644 index 000000000..a756abe34 --- /dev/null +++ b/src/UserGuide/Master/Tree/Tools-System/CLI_timecho.md @@ -0,0 +1,293 @@ + + +# Command Line Interface (CLI) + + +IoTDB provides Cli/shell tools for users to interact with IoTDB server in command lines. This document shows how Cli/shell tool works and the meaning of its parameters. + +> Note: In this document, \$IOTDB\_HOME represents the path of the IoTDB installation directory. + +## 1. Running Cli + +After installation, there is a default user in IoTDB: `root`, and the +default password is `root`. Users can use this username to try IoTDB Cli/Shell tool. The cli startup script is the `start-cli` file under the \$IOTDB\_HOME/bin folder. When starting the script, you need to specify the IP and PORT. (Make sure the IoTDB cluster is running properly when you use Cli/Shell tool to connect to it.) + +Here is an example where the cluster is started locally and the user has not changed the running port. The default rpc port is +6667
+If you need to connect to the remote DataNode or changes +the rpc port number of the DataNode running, set the specific IP and RPC PORT at -h and -p.
+You also can set your own environment variable at the front of the start script + +The Linux and MacOS system startup commands are as follows: + +```shell +Shell > bash sbin/start-cli.sh -h 127.0.0.1 -p 6667 -u root -pw root +``` + +The Windows system startup commands are as follows: + +```shell +# Before version V2.0.4.x +Shell > sbin\start-cli.bat -h 127.0.0.1 -p 6667 -u root -pw root + +# V2.0.4.x and later versions +Shell > sbin\windows\start-cli.bat -h 127.0.0.1 -p 6667 -u root -pw root +``` + +After operating these commands, the cli can be started successfully. The successful status will be as follows: + +``` + _____ _________ ______ ______ +|_ _| | _ _ ||_ _ `.|_ _ \ + | | .--.|_/ | | \_| | | `. \ | |_) | + | | / .'`\ \ | | | | | | | __'. + _| |_| \__. | _| |_ _| |_.' /_| |__) | +|_____|'.__.' |_____| |______.'|_______/ version + + +Successfully login at 127.0.0.1:6667 +IoTDB> +``` + +Enter ```quit``` or `exit` can exit Cli. + +## 2. Cli Parameters + +| Parameter name | Parameter type | Required | Description | Example | +| :--------------------------- | :------------------------- | :------- | :----------------------------------------------------------- | :------------------ | +| -disableISO8601 | No parameters | No | If this parameter is set, IoTDB will print the timestamp in digital form | -disableISO8601 | +| -h <`host`> | string, no quotation marks | Yes | The IP address of the IoTDB server | -h 10.129.187.21 | +| -help | No parameters | No | Print help information for IoTDB | -help | +| -p <`rpcPort`> | int | Yes | The rpc port number of the IoTDB server. IoTDB runs on rpc port 6667 by default | -p 6667 | +| -pw <`password`> | string, no quotation marks | No | The password used for IoTDB to connect to the server. If no password is entered, IoTDB will ask for password in Cli command | -pw root | +| -u <`username`> | string, no quotation marks | Yes | User name used for IoTDB to connect the server | -u root | +| -maxPRC <`maxPrintRowCount`> | int | No | Set the maximum number of rows that IoTDB returns | -maxPRC 10 | +| -e <`execute`> | string | No | manipulate IoTDB in batches without entering cli input mode | -e "show databases" | +| -c | empty | No | If the server enables `rpc_thrift_compression_enable=true`, then cli must use `-c` | -c | + +Following is a cli command which connects the host with IP +10.129.187.21, rpc port 6667, username "root", password "root", and prints the timestamp in digital form. The maximum number of lines displayed on the IoTDB command line is 10. + +The Linux and MacOS system startup commands are as follows: + +```shell +Shell > bash sbin/start-cli.sh -h 10.129.187.21 -p 6667 -u root -pw root -disableISO8601 -maxPRC 10 +``` + +The Windows system startup commands are as follows: + +```shell +# Before version V2.0.4.x +Shell > sbin\start-cli.bat -h 10.129.187.21 -p 6667 -u root -pw root -disableISO8601 -maxPRC 10 + +# # V2.0.4.x and later versions +Shell > sbin\windows\start-cli.bat -h 10.129.187.21 -p 6667 -u root -pw root -disableISO8601 -maxPRC 10 +``` + +## 3. CLI Special Command + +Special commands of Cli are below. + +| Command | Description / Example | +| :-------------------------- | :------------------------------------------------------ | +| `set time_display_type=xxx` | eg. long, default, ISO8601, yyyy-MM-dd HH:mm:ss | +| `show time_display_type` | show time display type | +| `set time_zone=xxx` | eg. +08:00, Asia/Shanghai | +| `show time_zone` | show cli time zone | +| `set fetch_size=xxx` | set fetch size when querying data from server | +| `show fetch_size` | show fetch size | +| `set max_display_num=xxx` | set max lines for cli to output, -1 equals to unlimited | +| `help` | Get hints for CLI special commands | +| `exit/quit` | Exit CLI | + +## 4. Note on using the CLI with OpenID Connect Auth enabled on Server side + +Openid connect (oidc) uses keycloack as the authority authentication service of oidc service + + +#### configuration + +The configuration is located in iotdb-system.properties , set the author_provider_class is org.apache.iotdb.commons.auth.authorizer.OpenIdAuthorizer Openid service is enabled, and the default value is org.apache.iotdb.db.auth.authorizer.LocalFileAuthorizer Indicates that the openid service is not enabled. + +``` +authorizer_provider_class=org.apache.iotdb.commons.auth.authorizer.OpenIdAuthorizer +``` + +If the openid service is turned on, openid_URL is required,openID_url value is http://ip:port/realms/{realmsName} + +``` +openID_url=http://127.0.0.1:8080/realms/iotdb/ +``` + +#### keycloack configuration + +1、Download the keycloack file (This tutorial is version 21.1.0) and start keycloack in keycloack/bin + +```shell +Shell >cd bin +Shell >./kc.sh start-dev +``` + +2、use url(https://ip:port) login keycloack, the first login needs to create a user +![avatar](/img/UserGuide/CLI/Command-Line-Interface/login_keycloak.png?raw=true) + +3、Click administration console +![avatar](/img/UserGuide/CLI/Command-Line-Interface/AdministrationConsole.png?raw=true) + +4、In the master menu on the left, click Create realm and enter Realm name to create a new realm +![avatar](/img/UserGuide/CLI/Command-Line-Interface/add_Realm_1.jpg?raw=true) + +![avatar](/img/UserGuide/CLI/Command-Line-Interface/add_Realm_2.jpg?raw=true) + + +5、Click the menu clients on the left to create clients + +![avatar](/img/UserGuide/CLI/Command-Line-Interface/client.jpg?raw=true) + +6、Click user on the left menu to create user + +![avatar](/img/UserGuide/CLI/Command-Line-Interface/user.jpg?raw=true) + +7、Click the newly created user ID, click the credentials navigation, enter the password and close the temporary option. The configuration of keycloud is completed + +![avatar](/img/UserGuide/CLI/Command-Line-Interface/pwd.jpg?raw=true) + +8、To create a role, click Roles on the left menu and then click the Create Role button to add a role + +![avatar](/img/UserGuide/CLI/Command-Line-Interface/add_role1.jpg?raw=true) + +9、 Enter `iotdb_admin` in the Role Name and click the save button. Tip: `iotdb_admin` here cannot be any other name, otherwise even after successful login, you will not have permission to use iotdb's query, insert, create database, add users, roles and other functions + +![avatar](/img/UserGuide/CLI/Command-Line-Interface/add_role2.jpg?raw=true) + +10、Click on the User menu on the left and then click on the user in the user list to add the `iotdb_admin` role we just created for that user + +![avatar](/img/UserGuide/CLI/Command-Line-Interface/add_role3.jpg?raw=true) + +11、 Select Role Mappings, select the `iotdb_admin` role in Assign Role + +![avatar](/img/UserGuide/CLI/Command-Line-Interface/add_role4.jpg?raw=true) + +![avatar](/img/UserGuide/CLI/Command-Line-Interface/add_role5.jpg?raw=true) + + +Tip: If the user role is adjusted, you need to regenerate the token and log in to iotdb again to take effect + +The above steps provide a way for keycloak to log into iotdb. For more ways, please refer to keycloak configuration + +If OIDC is enabled on server side then no username / passwort is needed but a valid Access Token from the OIDC Provider. +So as username you use the token and the password has to be empty, e.g. + +```shell +Shell > bash sbin/start-cli.sh -h 10.129.187.21 -p 6667 -u {my-access-token} -pw "" +``` + +Among them, you need to replace {my access token} (note, including {}) with your token, that is, the value corresponding to access_token. The password is empty and needs to be confirmed again. + +![avatar](/img/UserGuide/CLI/Command-Line-Interface/iotdbpw.jpeg?raw=true) + + +How to get the token is dependent on your OpenID Connect setup and not covered here. +In the simplest case you can get this via the command line with the `passwort-grant`. +For example, if you use keycloack as OIDC and you have a realm with a client `iotdb` defined as public you could use +the following `curl` command to fetch a token (replace all `{}` with appropriate values). + +```shell +curl -X POST "https://{your-keycloack-server}/realms/{your-realm}/protocol/openid-connect/token" \ + -H "Content-Type: application/x-www-form-urlencoded" \ + -d "username={username}" \ + -d "password={password}" \ + -d 'grant_type=password' \ + -d "client_id=iotdb-client" +``` + +The response looks something like + +```json +{"access_token":"eyJhbGciOiJSUzI1NiIsInR5cCIgOiAiSldUIiwia2lkIiA6ICJxMS1XbTBvelE1TzBtUUg4LVNKYXAyWmNONE1tdWNXd25RV0tZeFpKNG93In0.eyJleHAiOjE1OTAzOTgwNzEsImlhdCI6MTU5MDM5Nzc3MSwianRpIjoiNjA0ZmYxMDctN2NiNy00NTRmLWIwYmQtY2M2ZDQwMjFiNGU4IiwiaXNzIjoiaHR0cDovL2F1dGguZGVtby5wcmFnbWF0aWNpbmR1c3RyaWVzLmRlL2F1dGgvcmVhbG1zL0lvVERCIiwiYXVkIjoiYWNjb3VudCIsInN1YiI6ImJhMzJlNDcxLWM3NzItNGIzMy04ZGE2LTZmZThhY2RhMDA3MyIsInR5cCI6IkJlYXJlciIsImF6cCI6ImlvdGRiIiwic2Vzc2lvbl9zdGF0ZSI6IjA2MGQyODYyLTE0ZWQtNDJmZS1iYWY3LThkMWY3ODQ2NTdmMSIsImFjciI6IjEiLCJhbGxvd2VkLW9yaWdpbnMiOlsibG9jYWxob3N0OjgwODAiXSwicmVhbG1fYWNjZXNzIjp7InJvbGVzIjpbIm9mZmxpbmVfYWNjZXNzIiwidW1hX2F1dGhvcml6YXRpb24iLCJpb3RkYl9hZG1pbiJdfSwicmVzb3VyY2VfYWNjZXNzIjp7ImFjY291bnQiOnsicm9sZXMiOlsibWFuYWdlLWFjY291bnQiLCJtYW5hZ2UtYWNjb3VudC1saW5rcyIsInZpZXctcHJvZmlsZSJdfX0sInNjb3BlIjoiZW1haWwgcHJvZmlsZSIsImVtYWlsX3ZlcmlmaWVkIjp0cnVlLCJwcmVmZXJyZWRfdXNlcm5hbWUiOiJ1c2VyIn0.nwbrJkWdCNjzFrTDwKNuV5h9dDMg5ytRKGOXmFIajpfsbOutJytjWTCB2WpA8E1YI3KM6gU6Jx7cd7u0oPo5syHhfCz119n_wBiDnyTZkFOAPsx0M2z20kvBLN9k36_VfuCMFUeddJjO31MeLTmxB0UKg2VkxdczmzMH3pnalhxqpnWWk3GnrRrhAf2sZog0foH4Ae3Ks0lYtYzaWK_Yo7E4Px42-gJpohy3JevOC44aJ4auzJR1RBj9LUbgcRinkBy0JLi6XXiYznSC2V485CSBHW3sseXn7pSXQADhnmGQrLfFGO5ZljmPO18eFJaimdjvgSChsrlSEmTDDsoo5Q","expires_in":300,"refresh_expires_in":1800,"refresh_token":"eyJhbGciOiJIUzI1NiIsInR5cCIgOiAiSldUIiwia2lkIiA6ICJhMzZlMGU0NC02MWNmLTQ5NmMtOGRlZi03NTkwNjQ5MzQzMjEifQ.eyJleHAiOjE1OTAzOTk1NzEsImlhdCI6MTU5MDM5Nzc3MSwianRpIjoiNmMxNTBiY2EtYmE5NC00NTgxLWEwODEtYjI2YzhhMmI5YmZmIiwiaXNzIjoiaHR0cDovL2F1dGguZGVtby5wcmFnbWF0aWNpbmR1c3RyaWVzLmRlL2F1dGgvcmVhbG1zL0lvVERCIiwiYXVkIjoiaHR0cDovL2F1dGguZGVtby5wcmFnbWF0aWNpbmR1c3RyaWVzLmRlL2F1dGgvcmVhbG1zL0lvVERCIiwic3ViIjoiYmEzMmU0NzEtYzc3Mi00YjMzLThkYTYtNmZlOGFjZGEwMDczIiwidHlwIjoiUmVmcmVzaCIsImF6cCI6ImlvdGRiIiwic2Vzc2lvbl9zdGF0ZSI6IjA2MGQyODYyLTE0ZWQtNDJmZS1iYWY3LThkMWY3ODQ2NTdmMSIsInNjb3BlIjoiZW1haWwgcHJvZmlsZSJ9.ayNpXdNX28qahodX1zowrMGiUCw2AodlHBQFqr8Ui7c","token_type":"bearer","not-before-policy":0,"session_state":"060d2862-14ed-42fe-baf7-8d1f784657f1","scope":"email profile"} +``` + +The interesting part here is the access token with the key `access_token`. +This has to be passed as username (with parameter `-u`) and empty password to the CLI. + +## 5. Batch Operation of Cli + +-e parameter is designed for the Cli/shell tool in the situation where you would like to manipulate IoTDB in batches through scripts. By using the -e parameter, you can operate IoTDB without entering the cli's input mode. + +In order to avoid confusion between statements and other parameters, the current version only supports the -e parameter as the last parameter. + +The usage of -e parameter for Cli/shell is as follows: + +The Linux and MacOS system commands: + +```shell +Shell > bash sbin/start-cli.sh -h {host} -p {rpcPort} -u {user} -pw {password} -e {sql for iotdb} +``` + +The Windows system commands: + +```shell +# Before version V2.0.4.x +Shell > sbin\start-cli.bat -h {host} -p {rpcPort} -u {user} -pw {password} -e {sql for iotdb} + +# V2.0.4.x and later versions +Shell > sbin\windows\start-cli.bat -h {host} -p {rpcPort} -u {user} -pw {password} -e {sql for iotdb} +``` + +In the Windows environment, the SQL statement of the -e parameter needs to use ` `` ` to replace `" "` + +In order to better explain the use of -e parameter, take following as an example(On linux system). + +Suppose you want to create a database root.demo to a newly launched IoTDB, create a timeseries root.demo.s1 and insert three data points into it. With -e parameter, you could write a shell like this: + +```shell +# !/bin/bash + +host=127.0.0.1 +rpcPort=6667 +user=root +pass=root + +bash ./sbin/start-cli.sh -h ${host} -p ${rpcPort} -u ${user} -pw ${pass} -e "create database root.demo" +bash ./sbin/start-cli.sh -h ${host} -p ${rpcPort} -u ${user} -pw ${pass} -e "create timeseries root.demo.s1 WITH DATATYPE=INT32, ENCODING=RLE" +bash ./sbin/start-cli.sh -h ${host} -p ${rpcPort} -u ${user} -pw ${pass} -e "insert into root.demo(timestamp,s1) values(1,10)" +bash ./sbin/start-cli.sh -h ${host} -p ${rpcPort} -u ${user} -pw ${pass} -e "insert into root.demo(timestamp,s1) values(2,11)" +bash ./sbin/start-cli.sh -h ${host} -p ${rpcPort} -u ${user} -pw ${pass} -e "insert into root.demo(timestamp,s1) values(3,12)" +bash ./sbin/start-cli.sh -h ${host} -p ${rpcPort} -u ${user} -pw ${pass} -e "select s1 from root.demo" +``` + +The results are shown in the figure, which are consistent with the Cli and jdbc operations. + +```shell + Shell > bash ./shell.sh ++-----------------------------+------------+ +| Time|root.demo.s1| ++-----------------------------+------------+ +|1970-01-01T08:00:00.001+08:00| 10| +|1970-01-01T08:00:00.002+08:00| 11| +|1970-01-01T08:00:00.003+08:00| 12| ++-----------------------------+------------+ +Total line number = 3 +It costs 0.267s +``` + +It should be noted that the use of the -e parameter in shell scripts requires attention to the escaping of special characters. diff --git a/src/UserGuide/V1.3.x/Tools-System/CLI.md b/src/UserGuide/V1.3.x/Tools-System/CLI.md index 47a038952..03580fafb 100644 --- a/src/UserGuide/V1.3.x/Tools-System/CLI.md +++ b/src/UserGuide/V1.3.x/Tools-System/CLI.md @@ -1,3 +1,6 @@ +--- +redirectTo: CLI_apache.html +--- - -# Command Line Interface (CLI) - - -IoTDB provides Cli/shell tools for users to interact with IoTDB server in command lines. This document shows how Cli/shell tool works and the meaning of its parameters. - -> Note: In this document, \$IOTDB\_HOME represents the path of the IoTDB installation directory. - -## Installation - -If you use the source code version of IoTDB, then under the root path of IoTDB, execute: - -```shell -> mvn clean package -pl iotdb-client/cli -am -DskipTests -P get-jar-with-dependencies -``` - -After build, the IoTDB Cli will be in the folder "cli/target/iotdb-cli-{project.version}". - -If you download the binary version, then the Cli can be used directly in sbin folder. - -## Running - -### Running Cli - -After installation, there is a default user in IoTDB: `root`, and the -default password is `root`. Users can use this username to try IoTDB Cli/Shell tool. The cli startup script is the `start-cli` file under the \$IOTDB\_HOME/bin folder. When starting the script, you need to specify the IP and PORT. (Make sure the IoTDB cluster is running properly when you use Cli/Shell tool to connect to it.) - -Here is an example where the cluster is started locally and the user has not changed the running port. The default rpc port is -6667
-If you need to connect to the remote DataNode or changes -the rpc port number of the DataNode running, set the specific IP and RPC PORT at -h and -p.
-You also can set your own environment variable at the front of the start script ("/sbin/start-cli.sh" for linux and "/sbin/start-cli.bat" for windows) - -The Linux and MacOS system startup commands are as follows: - -```shell -Shell > bash sbin/start-cli.sh -h 127.0.0.1 -p 6667 -u root -pw root -``` - -The Windows system startup commands are as follows: - -```shell -Shell > sbin\start-cli.bat -h 127.0.0.1 -p 6667 -u root -pw root -``` - -After operating these commands, the cli can be started successfully. The successful status will be as follows: - -``` - _____ _________ ______ ______ -|_ _| | _ _ ||_ _ `.|_ _ \ - | | .--.|_/ | | \_| | | `. \ | |_) | - | | / .'`\ \ | | | | | | | __'. - _| |_| \__. | _| |_ _| |_.' /_| |__) | -|_____|'.__.' |_____| |______.'|_______/ version - - -Successfully login at 127.0.0.1:6667 -IoTDB> -``` - -Enter ```quit``` or `exit` can exit Cli. - -### Cli Parameters - -| Parameter name | Parameter type | Required | Description | Example | -| :--------------------------- | :------------------------- | :------- | :----------------------------------------------------------- | :------------------ | -| -disableISO8601 | No parameters | No | If this parameter is set, IoTDB will print the timestamp in digital form | -disableISO8601 | -| -h <`host`> | string, no quotation marks | Yes | The IP address of the IoTDB server | -h 10.129.187.21 | -| -help | No parameters | No | Print help information for IoTDB | -help | -| -p <`rpcPort`> | int | Yes | The rpc port number of the IoTDB server. IoTDB runs on rpc port 6667 by default | -p 6667 | -| -pw <`password`> | string, no quotation marks | No | The password used for IoTDB to connect to the server. If no password is entered, IoTDB will ask for password in Cli command | -pw root | -| -u <`username`> | string, no quotation marks | Yes | User name used for IoTDB to connect the server | -u root | -| -maxPRC <`maxPrintRowCount`> | int | No | Set the maximum number of rows that IoTDB returns | -maxPRC 10 | -| -e <`execute`> | string | No | manipulate IoTDB in batches without entering cli input mode | -e "show databases" | -| -c | empty | No | If the server enables `rpc_thrift_compression_enable=true`, then cli must use `-c` | -c | - -Following is a cli command which connects the host with IP -10.129.187.21, rpc port 6667, username "root", password "root", and prints the timestamp in digital form. The maximum number of lines displayed on the IoTDB command line is 10. - -The Linux and MacOS system startup commands are as follows: - -```shell -Shell > bash sbin/start-cli.sh -h 10.129.187.21 -p 6667 -u root -pw root -disableISO8601 -maxPRC 10 -``` - -The Windows system startup commands are as follows: - -```shell -Shell > sbin\start-cli.bat -h 10.129.187.21 -p 6667 -u root -pw root -disableISO8601 -maxPRC 10 -``` - -### CLI Special Command - -Special commands of Cli are below. - -| Command | Description / Example | -| :-------------------------- | :------------------------------------------------------ | -| `set time_display_type=xxx` | eg. long, default, ISO8601, yyyy-MM-dd HH:mm:ss | -| `show time_display_type` | show time display type | -| `set time_zone=xxx` | eg. +08:00, Asia/Shanghai | -| `show time_zone` | show cli time zone | -| `set fetch_size=xxx` | set fetch size when querying data from server | -| `show fetch_size` | show fetch size | -| `set max_display_num=xxx` | set max lines for cli to output, -1 equals to unlimited | -| `help` | Get hints for CLI special commands | -| `exit/quit` | Exit CLI | - -### Note on using the CLI with OpenID Connect Auth enabled on Server side - -Openid connect (oidc) uses keycloack as the authority authentication service of oidc service - - -#### configuration - -The configuration is located in iotdb-system.properties , set the author_provider_class is org.apache.iotdb.commons.auth.authorizer.OpenIdAuthorizer Openid service is enabled, and the default value is org.apache.iotdb.db.auth.authorizer.LocalFileAuthorizer Indicates that the openid service is not enabled. - -``` -authorizer_provider_class=org.apache.iotdb.commons.auth.authorizer.OpenIdAuthorizer -``` - -If the openid service is turned on, openid_URL is required,openID_url value is http://ip:port/realms/{realmsName} - -``` -openID_url=http://127.0.0.1:8080/realms/iotdb/ -``` - -#### keycloack configuration - -1、Download the keycloack file (This tutorial is version 21.1.0) and start keycloack in keycloack/bin - -```shell -Shell >cd bin -Shell >./kc.sh start-dev -``` - -2、use url(https://ip:port) login keycloack, the first login needs to create a user -![avatar](/img/UserGuide/CLI/Command-Line-Interface/login_keycloak.png?raw=true) - -3、Click administration console -![avatar](/img/UserGuide/CLI/Command-Line-Interface/AdministrationConsole.png?raw=true) - -4、In the master menu on the left, click Create realm and enter Realm name to create a new realm -![avatar](/img/UserGuide/CLI/Command-Line-Interface/add_Realm_1.jpg?raw=true) - -![avatar](/img/UserGuide/CLI/Command-Line-Interface/add_Realm_2.jpg?raw=true) - - -5、Click the menu clients on the left to create clients - -![avatar](/img/UserGuide/CLI/Command-Line-Interface/client.jpg?raw=true) - -6、Click user on the left menu to create user - -![avatar](/img/UserGuide/CLI/Command-Line-Interface/user.jpg?raw=true) - -7、Click the newly created user ID, click the credentials navigation, enter the password and close the temporary option. The configuration of keycloud is completed - -![avatar](/img/UserGuide/CLI/Command-Line-Interface/pwd.jpg?raw=true) - -8、To create a role, click Roles on the left menu and then click the Create Role button to add a role - -![avatar](/img/UserGuide/CLI/Command-Line-Interface/add_role1.jpg?raw=true) - -9、 Enter `iotdb_admin` in the Role Name and click the save button. Tip: `iotdb_admin` here cannot be any other name, otherwise even after successful login, you will not have permission to use iotdb's query, insert, create database, add users, roles and other functions - -![avatar](/img/UserGuide/CLI/Command-Line-Interface/add_role2.jpg?raw=true) - -10、Click on the User menu on the left and then click on the user in the user list to add the `iotdb_admin` role we just created for that user - -![avatar](/img/UserGuide/CLI/Command-Line-Interface/add_role3.jpg?raw=true) - -11、 Select Role Mappings, select the `iotdb_admin` role in Assign Role - -![avatar](/img/UserGuide/CLI/Command-Line-Interface/add_role4.jpg?raw=true) - -![avatar](/img/UserGuide/CLI/Command-Line-Interface/add_role5.jpg?raw=true) - - -Tip: If the user role is adjusted, you need to regenerate the token and log in to iotdb again to take effect - -The above steps provide a way for keycloak to log into iotdb. For more ways, please refer to keycloak configuration - -If OIDC is enabled on server side then no username / passwort is needed but a valid Access Token from the OIDC Provider. -So as username you use the token and the password has to be empty, e.g. - -```shell -Shell > bash sbin/start-cli.sh -h 10.129.187.21 -p 6667 -u {my-access-token} -pw "" -``` - -Among them, you need to replace {my access token} (note, including {}) with your token, that is, the value corresponding to access_token. The password is empty and needs to be confirmed again. - -![avatar](/img/UserGuide/CLI/Command-Line-Interface/iotdbpw.jpeg?raw=true) - - -How to get the token is dependent on your OpenID Connect setup and not covered here. -In the simplest case you can get this via the command line with the `passwort-grant`. -For example, if you use keycloack as OIDC and you have a realm with a client `iotdb` defined as public you could use -the following `curl` command to fetch a token (replace all `{}` with appropriate values). - -```shell -curl -X POST "https://{your-keycloack-server}/realms/{your-realm}/protocol/openid-connect/token" \ - -H "Content-Type: application/x-www-form-urlencoded" \ - -d "username={username}" \ - -d "password={password}" \ - -d 'grant_type=password' \ - -d "client_id=iotdb-client" -``` - -The response looks something like - -```json -{"access_token":"eyJhbGciOiJSUzI1NiIsInR5cCIgOiAiSldUIiwia2lkIiA6ICJxMS1XbTBvelE1TzBtUUg4LVNKYXAyWmNONE1tdWNXd25RV0tZeFpKNG93In0.eyJleHAiOjE1OTAzOTgwNzEsImlhdCI6MTU5MDM5Nzc3MSwianRpIjoiNjA0ZmYxMDctN2NiNy00NTRmLWIwYmQtY2M2ZDQwMjFiNGU4IiwiaXNzIjoiaHR0cDovL2F1dGguZGVtby5wcmFnbWF0aWNpbmR1c3RyaWVzLmRlL2F1dGgvcmVhbG1zL0lvVERCIiwiYXVkIjoiYWNjb3VudCIsInN1YiI6ImJhMzJlNDcxLWM3NzItNGIzMy04ZGE2LTZmZThhY2RhMDA3MyIsInR5cCI6IkJlYXJlciIsImF6cCI6ImlvdGRiIiwic2Vzc2lvbl9zdGF0ZSI6IjA2MGQyODYyLTE0ZWQtNDJmZS1iYWY3LThkMWY3ODQ2NTdmMSIsImFjciI6IjEiLCJhbGxvd2VkLW9yaWdpbnMiOlsibG9jYWxob3N0OjgwODAiXSwicmVhbG1fYWNjZXNzIjp7InJvbGVzIjpbIm9mZmxpbmVfYWNjZXNzIiwidW1hX2F1dGhvcml6YXRpb24iLCJpb3RkYl9hZG1pbiJdfSwicmVzb3VyY2VfYWNjZXNzIjp7ImFjY291bnQiOnsicm9sZXMiOlsibWFuYWdlLWFjY291bnQiLCJtYW5hZ2UtYWNjb3VudC1saW5rcyIsInZpZXctcHJvZmlsZSJdfX0sInNjb3BlIjoiZW1haWwgcHJvZmlsZSIsImVtYWlsX3ZlcmlmaWVkIjp0cnVlLCJwcmVmZXJyZWRfdXNlcm5hbWUiOiJ1c2VyIn0.nwbrJkWdCNjzFrTDwKNuV5h9dDMg5ytRKGOXmFIajpfsbOutJytjWTCB2WpA8E1YI3KM6gU6Jx7cd7u0oPo5syHhfCz119n_wBiDnyTZkFOAPsx0M2z20kvBLN9k36_VfuCMFUeddJjO31MeLTmxB0UKg2VkxdczmzMH3pnalhxqpnWWk3GnrRrhAf2sZog0foH4Ae3Ks0lYtYzaWK_Yo7E4Px42-gJpohy3JevOC44aJ4auzJR1RBj9LUbgcRinkBy0JLi6XXiYznSC2V485CSBHW3sseXn7pSXQADhnmGQrLfFGO5ZljmPO18eFJaimdjvgSChsrlSEmTDDsoo5Q","expires_in":300,"refresh_expires_in":1800,"refresh_token":"eyJhbGciOiJIUzI1NiIsInR5cCIgOiAiSldUIiwia2lkIiA6ICJhMzZlMGU0NC02MWNmLTQ5NmMtOGRlZi03NTkwNjQ5MzQzMjEifQ.eyJleHAiOjE1OTAzOTk1NzEsImlhdCI6MTU5MDM5Nzc3MSwianRpIjoiNmMxNTBiY2EtYmE5NC00NTgxLWEwODEtYjI2YzhhMmI5YmZmIiwiaXNzIjoiaHR0cDovL2F1dGguZGVtby5wcmFnbWF0aWNpbmR1c3RyaWVzLmRlL2F1dGgvcmVhbG1zL0lvVERCIiwiYXVkIjoiaHR0cDovL2F1dGguZGVtby5wcmFnbWF0aWNpbmR1c3RyaWVzLmRlL2F1dGgvcmVhbG1zL0lvVERCIiwic3ViIjoiYmEzMmU0NzEtYzc3Mi00YjMzLThkYTYtNmZlOGFjZGEwMDczIiwidHlwIjoiUmVmcmVzaCIsImF6cCI6ImlvdGRiIiwic2Vzc2lvbl9zdGF0ZSI6IjA2MGQyODYyLTE0ZWQtNDJmZS1iYWY3LThkMWY3ODQ2NTdmMSIsInNjb3BlIjoiZW1haWwgcHJvZmlsZSJ9.ayNpXdNX28qahodX1zowrMGiUCw2AodlHBQFqr8Ui7c","token_type":"bearer","not-before-policy":0,"session_state":"060d2862-14ed-42fe-baf7-8d1f784657f1","scope":"email profile"} -``` - -The interesting part here is the access token with the key `access_token`. -This has to be passed as username (with parameter `-u`) and empty password to the CLI. - -### Batch Operation of Cli - --e parameter is designed for the Cli/shell tool in the situation where you would like to manipulate IoTDB in batches through scripts. By using the -e parameter, you can operate IoTDB without entering the cli's input mode. - -In order to avoid confusion between statements and other parameters, the current version only supports the -e parameter as the last parameter. - -The usage of -e parameter for Cli/shell is as follows: - -The Linux and MacOS system commands: - -```shell -Shell > bash sbin/start-cli.sh -h {host} -p {rpcPort} -u {user} -pw {password} -e {sql for iotdb} -``` - -The Windows system commands: - -```shell -Shell > sbin\start-cli.bat -h {host} -p {rpcPort} -u {user} -pw {password} -e {sql for iotdb} -``` - -In the Windows environment, the SQL statement of the -e parameter needs to use ` `` ` to replace `" "` - -In order to better explain the use of -e parameter, take following as an example(On linux system). - -Suppose you want to create a database root.demo to a newly launched IoTDB, create a timeseries root.demo.s1 and insert three data points into it. With -e parameter, you could write a shell like this: - -```shell -# !/bin/bash - -host=127.0.0.1 -rpcPort=6667 -user=root -pass=root - -bash ./sbin/start-cli.sh -h ${host} -p ${rpcPort} -u ${user} -pw ${pass} -e "create database root.demo" -bash ./sbin/start-cli.sh -h ${host} -p ${rpcPort} -u ${user} -pw ${pass} -e "create timeseries root.demo.s1 WITH DATATYPE=INT32, ENCODING=RLE" -bash ./sbin/start-cli.sh -h ${host} -p ${rpcPort} -u ${user} -pw ${pass} -e "insert into root.demo(timestamp,s1) values(1,10)" -bash ./sbin/start-cli.sh -h ${host} -p ${rpcPort} -u ${user} -pw ${pass} -e "insert into root.demo(timestamp,s1) values(2,11)" -bash ./sbin/start-cli.sh -h ${host} -p ${rpcPort} -u ${user} -pw ${pass} -e "insert into root.demo(timestamp,s1) values(3,12)" -bash ./sbin/start-cli.sh -h ${host} -p ${rpcPort} -u ${user} -pw ${pass} -e "select s1 from root.demo" -``` - -The results are shown in the figure, which are consistent with the Cli and jdbc operations. - -```shell - Shell > bash ./shell.sh -+-----------------------------+------------+ -| Time|root.demo.s1| -+-----------------------------+------------+ -|1970-01-01T08:00:00.001+08:00| 10| -|1970-01-01T08:00:00.002+08:00| 11| -|1970-01-01T08:00:00.003+08:00| 12| -+-----------------------------+------------+ -Total line number = 3 -It costs 0.267s -``` - -It should be noted that the use of the -e parameter in shell scripts requires attention to the escaping of special characters. +--> \ No newline at end of file diff --git a/src/UserGuide/V1.3.x/Tools-System/CLI_apache.md b/src/UserGuide/V1.3.x/Tools-System/CLI_apache.md new file mode 100644 index 000000000..47a038952 --- /dev/null +++ b/src/UserGuide/V1.3.x/Tools-System/CLI_apache.md @@ -0,0 +1,295 @@ + + +# Command Line Interface (CLI) + + +IoTDB provides Cli/shell tools for users to interact with IoTDB server in command lines. This document shows how Cli/shell tool works and the meaning of its parameters. + +> Note: In this document, \$IOTDB\_HOME represents the path of the IoTDB installation directory. + +## Installation + +If you use the source code version of IoTDB, then under the root path of IoTDB, execute: + +```shell +> mvn clean package -pl iotdb-client/cli -am -DskipTests -P get-jar-with-dependencies +``` + +After build, the IoTDB Cli will be in the folder "cli/target/iotdb-cli-{project.version}". + +If you download the binary version, then the Cli can be used directly in sbin folder. + +## Running + +### Running Cli + +After installation, there is a default user in IoTDB: `root`, and the +default password is `root`. Users can use this username to try IoTDB Cli/Shell tool. The cli startup script is the `start-cli` file under the \$IOTDB\_HOME/bin folder. When starting the script, you need to specify the IP and PORT. (Make sure the IoTDB cluster is running properly when you use Cli/Shell tool to connect to it.) + +Here is an example where the cluster is started locally and the user has not changed the running port. The default rpc port is +6667
+If you need to connect to the remote DataNode or changes +the rpc port number of the DataNode running, set the specific IP and RPC PORT at -h and -p.
+You also can set your own environment variable at the front of the start script ("/sbin/start-cli.sh" for linux and "/sbin/start-cli.bat" for windows) + +The Linux and MacOS system startup commands are as follows: + +```shell +Shell > bash sbin/start-cli.sh -h 127.0.0.1 -p 6667 -u root -pw root +``` + +The Windows system startup commands are as follows: + +```shell +Shell > sbin\start-cli.bat -h 127.0.0.1 -p 6667 -u root -pw root +``` + +After operating these commands, the cli can be started successfully. The successful status will be as follows: + +``` + _____ _________ ______ ______ +|_ _| | _ _ ||_ _ `.|_ _ \ + | | .--.|_/ | | \_| | | `. \ | |_) | + | | / .'`\ \ | | | | | | | __'. + _| |_| \__. | _| |_ _| |_.' /_| |__) | +|_____|'.__.' |_____| |______.'|_______/ version + + +Successfully login at 127.0.0.1:6667 +IoTDB> +``` + +Enter ```quit``` or `exit` can exit Cli. + +### Cli Parameters + +| Parameter name | Parameter type | Required | Description | Example | +| :--------------------------- | :------------------------- | :------- | :----------------------------------------------------------- | :------------------ | +| -disableISO8601 | No parameters | No | If this parameter is set, IoTDB will print the timestamp in digital form | -disableISO8601 | +| -h <`host`> | string, no quotation marks | Yes | The IP address of the IoTDB server | -h 10.129.187.21 | +| -help | No parameters | No | Print help information for IoTDB | -help | +| -p <`rpcPort`> | int | Yes | The rpc port number of the IoTDB server. IoTDB runs on rpc port 6667 by default | -p 6667 | +| -pw <`password`> | string, no quotation marks | No | The password used for IoTDB to connect to the server. If no password is entered, IoTDB will ask for password in Cli command | -pw root | +| -u <`username`> | string, no quotation marks | Yes | User name used for IoTDB to connect the server | -u root | +| -maxPRC <`maxPrintRowCount`> | int | No | Set the maximum number of rows that IoTDB returns | -maxPRC 10 | +| -e <`execute`> | string | No | manipulate IoTDB in batches without entering cli input mode | -e "show databases" | +| -c | empty | No | If the server enables `rpc_thrift_compression_enable=true`, then cli must use `-c` | -c | + +Following is a cli command which connects the host with IP +10.129.187.21, rpc port 6667, username "root", password "root", and prints the timestamp in digital form. The maximum number of lines displayed on the IoTDB command line is 10. + +The Linux and MacOS system startup commands are as follows: + +```shell +Shell > bash sbin/start-cli.sh -h 10.129.187.21 -p 6667 -u root -pw root -disableISO8601 -maxPRC 10 +``` + +The Windows system startup commands are as follows: + +```shell +Shell > sbin\start-cli.bat -h 10.129.187.21 -p 6667 -u root -pw root -disableISO8601 -maxPRC 10 +``` + +### CLI Special Command + +Special commands of Cli are below. + +| Command | Description / Example | +| :-------------------------- | :------------------------------------------------------ | +| `set time_display_type=xxx` | eg. long, default, ISO8601, yyyy-MM-dd HH:mm:ss | +| `show time_display_type` | show time display type | +| `set time_zone=xxx` | eg. +08:00, Asia/Shanghai | +| `show time_zone` | show cli time zone | +| `set fetch_size=xxx` | set fetch size when querying data from server | +| `show fetch_size` | show fetch size | +| `set max_display_num=xxx` | set max lines for cli to output, -1 equals to unlimited | +| `help` | Get hints for CLI special commands | +| `exit/quit` | Exit CLI | + +### Note on using the CLI with OpenID Connect Auth enabled on Server side + +Openid connect (oidc) uses keycloack as the authority authentication service of oidc service + + +#### configuration + +The configuration is located in iotdb-system.properties , set the author_provider_class is org.apache.iotdb.commons.auth.authorizer.OpenIdAuthorizer Openid service is enabled, and the default value is org.apache.iotdb.db.auth.authorizer.LocalFileAuthorizer Indicates that the openid service is not enabled. + +``` +authorizer_provider_class=org.apache.iotdb.commons.auth.authorizer.OpenIdAuthorizer +``` + +If the openid service is turned on, openid_URL is required,openID_url value is http://ip:port/realms/{realmsName} + +``` +openID_url=http://127.0.0.1:8080/realms/iotdb/ +``` + +#### keycloack configuration + +1、Download the keycloack file (This tutorial is version 21.1.0) and start keycloack in keycloack/bin + +```shell +Shell >cd bin +Shell >./kc.sh start-dev +``` + +2、use url(https://ip:port) login keycloack, the first login needs to create a user +![avatar](/img/UserGuide/CLI/Command-Line-Interface/login_keycloak.png?raw=true) + +3、Click administration console +![avatar](/img/UserGuide/CLI/Command-Line-Interface/AdministrationConsole.png?raw=true) + +4、In the master menu on the left, click Create realm and enter Realm name to create a new realm +![avatar](/img/UserGuide/CLI/Command-Line-Interface/add_Realm_1.jpg?raw=true) + +![avatar](/img/UserGuide/CLI/Command-Line-Interface/add_Realm_2.jpg?raw=true) + + +5、Click the menu clients on the left to create clients + +![avatar](/img/UserGuide/CLI/Command-Line-Interface/client.jpg?raw=true) + +6、Click user on the left menu to create user + +![avatar](/img/UserGuide/CLI/Command-Line-Interface/user.jpg?raw=true) + +7、Click the newly created user ID, click the credentials navigation, enter the password and close the temporary option. The configuration of keycloud is completed + +![avatar](/img/UserGuide/CLI/Command-Line-Interface/pwd.jpg?raw=true) + +8、To create a role, click Roles on the left menu and then click the Create Role button to add a role + +![avatar](/img/UserGuide/CLI/Command-Line-Interface/add_role1.jpg?raw=true) + +9、 Enter `iotdb_admin` in the Role Name and click the save button. Tip: `iotdb_admin` here cannot be any other name, otherwise even after successful login, you will not have permission to use iotdb's query, insert, create database, add users, roles and other functions + +![avatar](/img/UserGuide/CLI/Command-Line-Interface/add_role2.jpg?raw=true) + +10、Click on the User menu on the left and then click on the user in the user list to add the `iotdb_admin` role we just created for that user + +![avatar](/img/UserGuide/CLI/Command-Line-Interface/add_role3.jpg?raw=true) + +11、 Select Role Mappings, select the `iotdb_admin` role in Assign Role + +![avatar](/img/UserGuide/CLI/Command-Line-Interface/add_role4.jpg?raw=true) + +![avatar](/img/UserGuide/CLI/Command-Line-Interface/add_role5.jpg?raw=true) + + +Tip: If the user role is adjusted, you need to regenerate the token and log in to iotdb again to take effect + +The above steps provide a way for keycloak to log into iotdb. For more ways, please refer to keycloak configuration + +If OIDC is enabled on server side then no username / passwort is needed but a valid Access Token from the OIDC Provider. +So as username you use the token and the password has to be empty, e.g. + +```shell +Shell > bash sbin/start-cli.sh -h 10.129.187.21 -p 6667 -u {my-access-token} -pw "" +``` + +Among them, you need to replace {my access token} (note, including {}) with your token, that is, the value corresponding to access_token. The password is empty and needs to be confirmed again. + +![avatar](/img/UserGuide/CLI/Command-Line-Interface/iotdbpw.jpeg?raw=true) + + +How to get the token is dependent on your OpenID Connect setup and not covered here. +In the simplest case you can get this via the command line with the `passwort-grant`. +For example, if you use keycloack as OIDC and you have a realm with a client `iotdb` defined as public you could use +the following `curl` command to fetch a token (replace all `{}` with appropriate values). + +```shell +curl -X POST "https://{your-keycloack-server}/realms/{your-realm}/protocol/openid-connect/token" \ + -H "Content-Type: application/x-www-form-urlencoded" \ + -d "username={username}" \ + -d "password={password}" \ + -d 'grant_type=password' \ + -d "client_id=iotdb-client" +``` + +The response looks something like + +```json +{"access_token":"eyJhbGciOiJSUzI1NiIsInR5cCIgOiAiSldUIiwia2lkIiA6ICJxMS1XbTBvelE1TzBtUUg4LVNKYXAyWmNONE1tdWNXd25RV0tZeFpKNG93In0.eyJleHAiOjE1OTAzOTgwNzEsImlhdCI6MTU5MDM5Nzc3MSwianRpIjoiNjA0ZmYxMDctN2NiNy00NTRmLWIwYmQtY2M2ZDQwMjFiNGU4IiwiaXNzIjoiaHR0cDovL2F1dGguZGVtby5wcmFnbWF0aWNpbmR1c3RyaWVzLmRlL2F1dGgvcmVhbG1zL0lvVERCIiwiYXVkIjoiYWNjb3VudCIsInN1YiI6ImJhMzJlNDcxLWM3NzItNGIzMy04ZGE2LTZmZThhY2RhMDA3MyIsInR5cCI6IkJlYXJlciIsImF6cCI6ImlvdGRiIiwic2Vzc2lvbl9zdGF0ZSI6IjA2MGQyODYyLTE0ZWQtNDJmZS1iYWY3LThkMWY3ODQ2NTdmMSIsImFjciI6IjEiLCJhbGxvd2VkLW9yaWdpbnMiOlsibG9jYWxob3N0OjgwODAiXSwicmVhbG1fYWNjZXNzIjp7InJvbGVzIjpbIm9mZmxpbmVfYWNjZXNzIiwidW1hX2F1dGhvcml6YXRpb24iLCJpb3RkYl9hZG1pbiJdfSwicmVzb3VyY2VfYWNjZXNzIjp7ImFjY291bnQiOnsicm9sZXMiOlsibWFuYWdlLWFjY291bnQiLCJtYW5hZ2UtYWNjb3VudC1saW5rcyIsInZpZXctcHJvZmlsZSJdfX0sInNjb3BlIjoiZW1haWwgcHJvZmlsZSIsImVtYWlsX3ZlcmlmaWVkIjp0cnVlLCJwcmVmZXJyZWRfdXNlcm5hbWUiOiJ1c2VyIn0.nwbrJkWdCNjzFrTDwKNuV5h9dDMg5ytRKGOXmFIajpfsbOutJytjWTCB2WpA8E1YI3KM6gU6Jx7cd7u0oPo5syHhfCz119n_wBiDnyTZkFOAPsx0M2z20kvBLN9k36_VfuCMFUeddJjO31MeLTmxB0UKg2VkxdczmzMH3pnalhxqpnWWk3GnrRrhAf2sZog0foH4Ae3Ks0lYtYzaWK_Yo7E4Px42-gJpohy3JevOC44aJ4auzJR1RBj9LUbgcRinkBy0JLi6XXiYznSC2V485CSBHW3sseXn7pSXQADhnmGQrLfFGO5ZljmPO18eFJaimdjvgSChsrlSEmTDDsoo5Q","expires_in":300,"refresh_expires_in":1800,"refresh_token":"eyJhbGciOiJIUzI1NiIsInR5cCIgOiAiSldUIiwia2lkIiA6ICJhMzZlMGU0NC02MWNmLTQ5NmMtOGRlZi03NTkwNjQ5MzQzMjEifQ.eyJleHAiOjE1OTAzOTk1NzEsImlhdCI6MTU5MDM5Nzc3MSwianRpIjoiNmMxNTBiY2EtYmE5NC00NTgxLWEwODEtYjI2YzhhMmI5YmZmIiwiaXNzIjoiaHR0cDovL2F1dGguZGVtby5wcmFnbWF0aWNpbmR1c3RyaWVzLmRlL2F1dGgvcmVhbG1zL0lvVERCIiwiYXVkIjoiaHR0cDovL2F1dGguZGVtby5wcmFnbWF0aWNpbmR1c3RyaWVzLmRlL2F1dGgvcmVhbG1zL0lvVERCIiwic3ViIjoiYmEzMmU0NzEtYzc3Mi00YjMzLThkYTYtNmZlOGFjZGEwMDczIiwidHlwIjoiUmVmcmVzaCIsImF6cCI6ImlvdGRiIiwic2Vzc2lvbl9zdGF0ZSI6IjA2MGQyODYyLTE0ZWQtNDJmZS1iYWY3LThkMWY3ODQ2NTdmMSIsInNjb3BlIjoiZW1haWwgcHJvZmlsZSJ9.ayNpXdNX28qahodX1zowrMGiUCw2AodlHBQFqr8Ui7c","token_type":"bearer","not-before-policy":0,"session_state":"060d2862-14ed-42fe-baf7-8d1f784657f1","scope":"email profile"} +``` + +The interesting part here is the access token with the key `access_token`. +This has to be passed as username (with parameter `-u`) and empty password to the CLI. + +### Batch Operation of Cli + +-e parameter is designed for the Cli/shell tool in the situation where you would like to manipulate IoTDB in batches through scripts. By using the -e parameter, you can operate IoTDB without entering the cli's input mode. + +In order to avoid confusion between statements and other parameters, the current version only supports the -e parameter as the last parameter. + +The usage of -e parameter for Cli/shell is as follows: + +The Linux and MacOS system commands: + +```shell +Shell > bash sbin/start-cli.sh -h {host} -p {rpcPort} -u {user} -pw {password} -e {sql for iotdb} +``` + +The Windows system commands: + +```shell +Shell > sbin\start-cli.bat -h {host} -p {rpcPort} -u {user} -pw {password} -e {sql for iotdb} +``` + +In the Windows environment, the SQL statement of the -e parameter needs to use ` `` ` to replace `" "` + +In order to better explain the use of -e parameter, take following as an example(On linux system). + +Suppose you want to create a database root.demo to a newly launched IoTDB, create a timeseries root.demo.s1 and insert three data points into it. With -e parameter, you could write a shell like this: + +```shell +# !/bin/bash + +host=127.0.0.1 +rpcPort=6667 +user=root +pass=root + +bash ./sbin/start-cli.sh -h ${host} -p ${rpcPort} -u ${user} -pw ${pass} -e "create database root.demo" +bash ./sbin/start-cli.sh -h ${host} -p ${rpcPort} -u ${user} -pw ${pass} -e "create timeseries root.demo.s1 WITH DATATYPE=INT32, ENCODING=RLE" +bash ./sbin/start-cli.sh -h ${host} -p ${rpcPort} -u ${user} -pw ${pass} -e "insert into root.demo(timestamp,s1) values(1,10)" +bash ./sbin/start-cli.sh -h ${host} -p ${rpcPort} -u ${user} -pw ${pass} -e "insert into root.demo(timestamp,s1) values(2,11)" +bash ./sbin/start-cli.sh -h ${host} -p ${rpcPort} -u ${user} -pw ${pass} -e "insert into root.demo(timestamp,s1) values(3,12)" +bash ./sbin/start-cli.sh -h ${host} -p ${rpcPort} -u ${user} -pw ${pass} -e "select s1 from root.demo" +``` + +The results are shown in the figure, which are consistent with the Cli and jdbc operations. + +```shell + Shell > bash ./shell.sh ++-----------------------------+------------+ +| Time|root.demo.s1| ++-----------------------------+------------+ +|1970-01-01T08:00:00.001+08:00| 10| +|1970-01-01T08:00:00.002+08:00| 11| +|1970-01-01T08:00:00.003+08:00| 12| ++-----------------------------+------------+ +Total line number = 3 +It costs 0.267s +``` + +It should be noted that the use of the -e parameter in shell scripts requires attention to the escaping of special characters. diff --git a/src/UserGuide/V1.3.x/Tools-System/CLI_timecho.md b/src/UserGuide/V1.3.x/Tools-System/CLI_timecho.md new file mode 100644 index 000000000..dfc5fdc56 --- /dev/null +++ b/src/UserGuide/V1.3.x/Tools-System/CLI_timecho.md @@ -0,0 +1,281 @@ + + +# Command Line Interface (CLI) + + +IoTDB provides Cli/shell tools for users to interact with IoTDB server in command lines. This document shows how Cli/shell tool works and the meaning of its parameters. + +> Note: In this document, \$IOTDB\_HOME represents the path of the IoTDB installation directory. + +## Running Cli + +After installation, there is a default user in IoTDB: `root`, and the +default password is `root`. Users can use this username to try IoTDB Cli/Shell tool. The cli startup script is the `start-cli` file under the \$IOTDB\_HOME/bin folder. When starting the script, you need to specify the IP and PORT. (Make sure the IoTDB cluster is running properly when you use Cli/Shell tool to connect to it.) + +Here is an example where the cluster is started locally and the user has not changed the running port. The default rpc port is +6667
+If you need to connect to the remote DataNode or changes +the rpc port number of the DataNode running, set the specific IP and RPC PORT at -h and -p.
+You also can set your own environment variable at the front of the start script ("/sbin/start-cli.sh" for linux and "/sbin/start-cli.bat" for windows) + +The Linux and MacOS system startup commands are as follows: + +```shell +Shell > bash sbin/start-cli.sh -h 127.0.0.1 -p 6667 -u root -pw root +``` + +The Windows system startup commands are as follows: + +```shell +Shell > sbin\start-cli.bat -h 127.0.0.1 -p 6667 -u root -pw root +``` + +After operating these commands, the cli can be started successfully. The successful status will be as follows: + +``` + _____ _________ ______ ______ +|_ _| | _ _ ||_ _ `.|_ _ \ + | | .--.|_/ | | \_| | | `. \ | |_) | + | | / .'`\ \ | | | | | | | __'. + _| |_| \__. | _| |_ _| |_.' /_| |__) | +|_____|'.__.' |_____| |______.'|_______/ version + + +Successfully login at 127.0.0.1:6667 +IoTDB> +``` + +Enter ```quit``` or `exit` can exit Cli. + +## Cli Parameters + +| Parameter name | Parameter type | Required | Description | Example | +| :--------------------------- | :------------------------- | :------- | :----------------------------------------------------------- | :------------------ | +| -disableISO8601 | No parameters | No | If this parameter is set, IoTDB will print the timestamp in digital form | -disableISO8601 | +| -h <`host`> | string, no quotation marks | Yes | The IP address of the IoTDB server | -h 10.129.187.21 | +| -help | No parameters | No | Print help information for IoTDB | -help | +| -p <`rpcPort`> | int | Yes | The rpc port number of the IoTDB server. IoTDB runs on rpc port 6667 by default | -p 6667 | +| -pw <`password`> | string, no quotation marks | No | The password used for IoTDB to connect to the server. If no password is entered, IoTDB will ask for password in Cli command | -pw root | +| -u <`username`> | string, no quotation marks | Yes | User name used for IoTDB to connect the server | -u root | +| -maxPRC <`maxPrintRowCount`> | int | No | Set the maximum number of rows that IoTDB returns | -maxPRC 10 | +| -e <`execute`> | string | No | manipulate IoTDB in batches without entering cli input mode | -e "show databases" | +| -c | empty | No | If the server enables `rpc_thrift_compression_enable=true`, then cli must use `-c` | -c | + +Following is a cli command which connects the host with IP +10.129.187.21, rpc port 6667, username "root", password "root", and prints the timestamp in digital form. The maximum number of lines displayed on the IoTDB command line is 10. + +The Linux and MacOS system startup commands are as follows: + +```shell +Shell > bash sbin/start-cli.sh -h 10.129.187.21 -p 6667 -u root -pw root -disableISO8601 -maxPRC 10 +``` + +The Windows system startup commands are as follows: + +```shell +Shell > sbin\start-cli.bat -h 10.129.187.21 -p 6667 -u root -pw root -disableISO8601 -maxPRC 10 +``` + +## CLI Special Command + +Special commands of Cli are below. + +| Command | Description / Example | +| :-------------------------- | :------------------------------------------------------ | +| `set time_display_type=xxx` | eg. long, default, ISO8601, yyyy-MM-dd HH:mm:ss | +| `show time_display_type` | show time display type | +| `set time_zone=xxx` | eg. +08:00, Asia/Shanghai | +| `show time_zone` | show cli time zone | +| `set fetch_size=xxx` | set fetch size when querying data from server | +| `show fetch_size` | show fetch size | +| `set max_display_num=xxx` | set max lines for cli to output, -1 equals to unlimited | +| `help` | Get hints for CLI special commands | +| `exit/quit` | Exit CLI | + +## Note on using the CLI with OpenID Connect Auth enabled on Server side + +Openid connect (oidc) uses keycloack as the authority authentication service of oidc service + + +### configuration + +The configuration is located in iotdb-system.properties , set the author_provider_class is org.apache.iotdb.commons.auth.authorizer.OpenIdAuthorizer Openid service is enabled, and the default value is org.apache.iotdb.db.auth.authorizer.LocalFileAuthorizer Indicates that the openid service is not enabled. + +``` +authorizer_provider_class=org.apache.iotdb.commons.auth.authorizer.OpenIdAuthorizer +``` + +If the openid service is turned on, openid_URL is required,openID_url value is http://ip:port/realms/{realmsName} + +``` +openID_url=http://127.0.0.1:8080/realms/iotdb/ +``` + +### keycloack configuration + +1、Download the keycloack file (This tutorial is version 21.1.0) and start keycloack in keycloack/bin + +```shell +Shell >cd bin +Shell >./kc.sh start-dev +``` + +2、use url(https://ip:port) login keycloack, the first login needs to create a user +![avatar](/img/UserGuide/CLI/Command-Line-Interface/login_keycloak.png?raw=true) + +3、Click administration console +![avatar](/img/UserGuide/CLI/Command-Line-Interface/AdministrationConsole.png?raw=true) + +4、In the master menu on the left, click Create realm and enter Realm name to create a new realm +![avatar](/img/UserGuide/CLI/Command-Line-Interface/add_Realm_1.jpg?raw=true) + +![avatar](/img/UserGuide/CLI/Command-Line-Interface/add_Realm_2.jpg?raw=true) + + +5、Click the menu clients on the left to create clients + +![avatar](/img/UserGuide/CLI/Command-Line-Interface/client.jpg?raw=true) + +6、Click user on the left menu to create user + +![avatar](/img/UserGuide/CLI/Command-Line-Interface/user.jpg?raw=true) + +7、Click the newly created user ID, click the credentials navigation, enter the password and close the temporary option. The configuration of keycloud is completed + +![avatar](/img/UserGuide/CLI/Command-Line-Interface/pwd.jpg?raw=true) + +8、To create a role, click Roles on the left menu and then click the Create Role button to add a role + +![avatar](/img/UserGuide/CLI/Command-Line-Interface/add_role1.jpg?raw=true) + +9、 Enter `iotdb_admin` in the Role Name and click the save button. Tip: `iotdb_admin` here cannot be any other name, otherwise even after successful login, you will not have permission to use iotdb's query, insert, create database, add users, roles and other functions + +![avatar](/img/UserGuide/CLI/Command-Line-Interface/add_role2.jpg?raw=true) + +10、Click on the User menu on the left and then click on the user in the user list to add the `iotdb_admin` role we just created for that user + +![avatar](/img/UserGuide/CLI/Command-Line-Interface/add_role3.jpg?raw=true) + +11、 Select Role Mappings, select the `iotdb_admin` role in Assign Role + +![avatar](/img/UserGuide/CLI/Command-Line-Interface/add_role4.jpg?raw=true) + +![avatar](/img/UserGuide/CLI/Command-Line-Interface/add_role5.jpg?raw=true) + + +Tip: If the user role is adjusted, you need to regenerate the token and log in to iotdb again to take effect + +The above steps provide a way for keycloak to log into iotdb. For more ways, please refer to keycloak configuration + +If OIDC is enabled on server side then no username / passwort is needed but a valid Access Token from the OIDC Provider. +So as username you use the token and the password has to be empty, e.g. + +```shell +Shell > bash sbin/start-cli.sh -h 10.129.187.21 -p 6667 -u {my-access-token} -pw "" +``` + +Among them, you need to replace {my access token} (note, including {}) with your token, that is, the value corresponding to access_token. The password is empty and needs to be confirmed again. + +![avatar](/img/UserGuide/CLI/Command-Line-Interface/iotdbpw.jpeg?raw=true) + + +How to get the token is dependent on your OpenID Connect setup and not covered here. +In the simplest case you can get this via the command line with the `passwort-grant`. +For example, if you use keycloack as OIDC and you have a realm with a client `iotdb` defined as public you could use +the following `curl` command to fetch a token (replace all `{}` with appropriate values). + +```shell +curl -X POST "https://{your-keycloack-server}/realms/{your-realm}/protocol/openid-connect/token" \ + -H "Content-Type: application/x-www-form-urlencoded" \ + -d "username={username}" \ + -d "password={password}" \ + -d 'grant_type=password' \ + -d "client_id=iotdb-client" +``` + +The response looks something like + +```json +{"access_token":"eyJhbGciOiJSUzI1NiIsInR5cCIgOiAiSldUIiwia2lkIiA6ICJxMS1XbTBvelE1TzBtUUg4LVNKYXAyWmNONE1tdWNXd25RV0tZeFpKNG93In0.eyJleHAiOjE1OTAzOTgwNzEsImlhdCI6MTU5MDM5Nzc3MSwianRpIjoiNjA0ZmYxMDctN2NiNy00NTRmLWIwYmQtY2M2ZDQwMjFiNGU4IiwiaXNzIjoiaHR0cDovL2F1dGguZGVtby5wcmFnbWF0aWNpbmR1c3RyaWVzLmRlL2F1dGgvcmVhbG1zL0lvVERCIiwiYXVkIjoiYWNjb3VudCIsInN1YiI6ImJhMzJlNDcxLWM3NzItNGIzMy04ZGE2LTZmZThhY2RhMDA3MyIsInR5cCI6IkJlYXJlciIsImF6cCI6ImlvdGRiIiwic2Vzc2lvbl9zdGF0ZSI6IjA2MGQyODYyLTE0ZWQtNDJmZS1iYWY3LThkMWY3ODQ2NTdmMSIsImFjciI6IjEiLCJhbGxvd2VkLW9yaWdpbnMiOlsibG9jYWxob3N0OjgwODAiXSwicmVhbG1fYWNjZXNzIjp7InJvbGVzIjpbIm9mZmxpbmVfYWNjZXNzIiwidW1hX2F1dGhvcml6YXRpb24iLCJpb3RkYl9hZG1pbiJdfSwicmVzb3VyY2VfYWNjZXNzIjp7ImFjY291bnQiOnsicm9sZXMiOlsibWFuYWdlLWFjY291bnQiLCJtYW5hZ2UtYWNjb3VudC1saW5rcyIsInZpZXctcHJvZmlsZSJdfX0sInNjb3BlIjoiZW1haWwgcHJvZmlsZSIsImVtYWlsX3ZlcmlmaWVkIjp0cnVlLCJwcmVmZXJyZWRfdXNlcm5hbWUiOiJ1c2VyIn0.nwbrJkWdCNjzFrTDwKNuV5h9dDMg5ytRKGOXmFIajpfsbOutJytjWTCB2WpA8E1YI3KM6gU6Jx7cd7u0oPo5syHhfCz119n_wBiDnyTZkFOAPsx0M2z20kvBLN9k36_VfuCMFUeddJjO31MeLTmxB0UKg2VkxdczmzMH3pnalhxqpnWWk3GnrRrhAf2sZog0foH4Ae3Ks0lYtYzaWK_Yo7E4Px42-gJpohy3JevOC44aJ4auzJR1RBj9LUbgcRinkBy0JLi6XXiYznSC2V485CSBHW3sseXn7pSXQADhnmGQrLfFGO5ZljmPO18eFJaimdjvgSChsrlSEmTDDsoo5Q","expires_in":300,"refresh_expires_in":1800,"refresh_token":"eyJhbGciOiJIUzI1NiIsInR5cCIgOiAiSldUIiwia2lkIiA6ICJhMzZlMGU0NC02MWNmLTQ5NmMtOGRlZi03NTkwNjQ5MzQzMjEifQ.eyJleHAiOjE1OTAzOTk1NzEsImlhdCI6MTU5MDM5Nzc3MSwianRpIjoiNmMxNTBiY2EtYmE5NC00NTgxLWEwODEtYjI2YzhhMmI5YmZmIiwiaXNzIjoiaHR0cDovL2F1dGguZGVtby5wcmFnbWF0aWNpbmR1c3RyaWVzLmRlL2F1dGgvcmVhbG1zL0lvVERCIiwiYXVkIjoiaHR0cDovL2F1dGguZGVtby5wcmFnbWF0aWNpbmR1c3RyaWVzLmRlL2F1dGgvcmVhbG1zL0lvVERCIiwic3ViIjoiYmEzMmU0NzEtYzc3Mi00YjMzLThkYTYtNmZlOGFjZGEwMDczIiwidHlwIjoiUmVmcmVzaCIsImF6cCI6ImlvdGRiIiwic2Vzc2lvbl9zdGF0ZSI6IjA2MGQyODYyLTE0ZWQtNDJmZS1iYWY3LThkMWY3ODQ2NTdmMSIsInNjb3BlIjoiZW1haWwgcHJvZmlsZSJ9.ayNpXdNX28qahodX1zowrMGiUCw2AodlHBQFqr8Ui7c","token_type":"bearer","not-before-policy":0,"session_state":"060d2862-14ed-42fe-baf7-8d1f784657f1","scope":"email profile"} +``` + +The interesting part here is the access token with the key `access_token`. +This has to be passed as username (with parameter `-u`) and empty password to the CLI. + +## Batch Operation of Cli + +-e parameter is designed for the Cli/shell tool in the situation where you would like to manipulate IoTDB in batches through scripts. By using the -e parameter, you can operate IoTDB without entering the cli's input mode. + +In order to avoid confusion between statements and other parameters, the current version only supports the -e parameter as the last parameter. + +The usage of -e parameter for Cli/shell is as follows: + +The Linux and MacOS system commands: + +```shell +Shell > bash sbin/start-cli.sh -h {host} -p {rpcPort} -u {user} -pw {password} -e {sql for iotdb} +``` + +The Windows system commands: + +```shell +Shell > sbin\start-cli.bat -h {host} -p {rpcPort} -u {user} -pw {password} -e {sql for iotdb} +``` + +In the Windows environment, the SQL statement of the -e parameter needs to use ` `` ` to replace `" "` + +In order to better explain the use of -e parameter, take following as an example(On linux system). + +Suppose you want to create a database root.demo to a newly launched IoTDB, create a timeseries root.demo.s1 and insert three data points into it. With -e parameter, you could write a shell like this: + +```shell +# !/bin/bash + +host=127.0.0.1 +rpcPort=6667 +user=root +pass=root + +bash ./sbin/start-cli.sh -h ${host} -p ${rpcPort} -u ${user} -pw ${pass} -e "create database root.demo" +bash ./sbin/start-cli.sh -h ${host} -p ${rpcPort} -u ${user} -pw ${pass} -e "create timeseries root.demo.s1 WITH DATATYPE=INT32, ENCODING=RLE" +bash ./sbin/start-cli.sh -h ${host} -p ${rpcPort} -u ${user} -pw ${pass} -e "insert into root.demo(timestamp,s1) values(1,10)" +bash ./sbin/start-cli.sh -h ${host} -p ${rpcPort} -u ${user} -pw ${pass} -e "insert into root.demo(timestamp,s1) values(2,11)" +bash ./sbin/start-cli.sh -h ${host} -p ${rpcPort} -u ${user} -pw ${pass} -e "insert into root.demo(timestamp,s1) values(3,12)" +bash ./sbin/start-cli.sh -h ${host} -p ${rpcPort} -u ${user} -pw ${pass} -e "select s1 from root.demo" +``` + +The results are shown in the figure, which are consistent with the Cli and jdbc operations. + +```shell + Shell > bash ./shell.sh ++-----------------------------+------------+ +| Time|root.demo.s1| ++-----------------------------+------------+ +|1970-01-01T08:00:00.001+08:00| 10| +|1970-01-01T08:00:00.002+08:00| 11| +|1970-01-01T08:00:00.003+08:00| 12| ++-----------------------------+------------+ +Total line number = 3 +It costs 0.267s +``` + +It should be noted that the use of the -e parameter in shell scripts requires attention to the escaping of special characters. diff --git a/src/UserGuide/dev-1.3/Tools-System/CLI.md b/src/UserGuide/dev-1.3/Tools-System/CLI.md index 47a038952..03580fafb 100644 --- a/src/UserGuide/dev-1.3/Tools-System/CLI.md +++ b/src/UserGuide/dev-1.3/Tools-System/CLI.md @@ -1,3 +1,6 @@ +--- +redirectTo: CLI_apache.html +--- - -# Command Line Interface (CLI) - - -IoTDB provides Cli/shell tools for users to interact with IoTDB server in command lines. This document shows how Cli/shell tool works and the meaning of its parameters. - -> Note: In this document, \$IOTDB\_HOME represents the path of the IoTDB installation directory. - -## Installation - -If you use the source code version of IoTDB, then under the root path of IoTDB, execute: - -```shell -> mvn clean package -pl iotdb-client/cli -am -DskipTests -P get-jar-with-dependencies -``` - -After build, the IoTDB Cli will be in the folder "cli/target/iotdb-cli-{project.version}". - -If you download the binary version, then the Cli can be used directly in sbin folder. - -## Running - -### Running Cli - -After installation, there is a default user in IoTDB: `root`, and the -default password is `root`. Users can use this username to try IoTDB Cli/Shell tool. The cli startup script is the `start-cli` file under the \$IOTDB\_HOME/bin folder. When starting the script, you need to specify the IP and PORT. (Make sure the IoTDB cluster is running properly when you use Cli/Shell tool to connect to it.) - -Here is an example where the cluster is started locally and the user has not changed the running port. The default rpc port is -6667
-If you need to connect to the remote DataNode or changes -the rpc port number of the DataNode running, set the specific IP and RPC PORT at -h and -p.
-You also can set your own environment variable at the front of the start script ("/sbin/start-cli.sh" for linux and "/sbin/start-cli.bat" for windows) - -The Linux and MacOS system startup commands are as follows: - -```shell -Shell > bash sbin/start-cli.sh -h 127.0.0.1 -p 6667 -u root -pw root -``` - -The Windows system startup commands are as follows: - -```shell -Shell > sbin\start-cli.bat -h 127.0.0.1 -p 6667 -u root -pw root -``` - -After operating these commands, the cli can be started successfully. The successful status will be as follows: - -``` - _____ _________ ______ ______ -|_ _| | _ _ ||_ _ `.|_ _ \ - | | .--.|_/ | | \_| | | `. \ | |_) | - | | / .'`\ \ | | | | | | | __'. - _| |_| \__. | _| |_ _| |_.' /_| |__) | -|_____|'.__.' |_____| |______.'|_______/ version - - -Successfully login at 127.0.0.1:6667 -IoTDB> -``` - -Enter ```quit``` or `exit` can exit Cli. - -### Cli Parameters - -| Parameter name | Parameter type | Required | Description | Example | -| :--------------------------- | :------------------------- | :------- | :----------------------------------------------------------- | :------------------ | -| -disableISO8601 | No parameters | No | If this parameter is set, IoTDB will print the timestamp in digital form | -disableISO8601 | -| -h <`host`> | string, no quotation marks | Yes | The IP address of the IoTDB server | -h 10.129.187.21 | -| -help | No parameters | No | Print help information for IoTDB | -help | -| -p <`rpcPort`> | int | Yes | The rpc port number of the IoTDB server. IoTDB runs on rpc port 6667 by default | -p 6667 | -| -pw <`password`> | string, no quotation marks | No | The password used for IoTDB to connect to the server. If no password is entered, IoTDB will ask for password in Cli command | -pw root | -| -u <`username`> | string, no quotation marks | Yes | User name used for IoTDB to connect the server | -u root | -| -maxPRC <`maxPrintRowCount`> | int | No | Set the maximum number of rows that IoTDB returns | -maxPRC 10 | -| -e <`execute`> | string | No | manipulate IoTDB in batches without entering cli input mode | -e "show databases" | -| -c | empty | No | If the server enables `rpc_thrift_compression_enable=true`, then cli must use `-c` | -c | - -Following is a cli command which connects the host with IP -10.129.187.21, rpc port 6667, username "root", password "root", and prints the timestamp in digital form. The maximum number of lines displayed on the IoTDB command line is 10. - -The Linux and MacOS system startup commands are as follows: - -```shell -Shell > bash sbin/start-cli.sh -h 10.129.187.21 -p 6667 -u root -pw root -disableISO8601 -maxPRC 10 -``` - -The Windows system startup commands are as follows: - -```shell -Shell > sbin\start-cli.bat -h 10.129.187.21 -p 6667 -u root -pw root -disableISO8601 -maxPRC 10 -``` - -### CLI Special Command - -Special commands of Cli are below. - -| Command | Description / Example | -| :-------------------------- | :------------------------------------------------------ | -| `set time_display_type=xxx` | eg. long, default, ISO8601, yyyy-MM-dd HH:mm:ss | -| `show time_display_type` | show time display type | -| `set time_zone=xxx` | eg. +08:00, Asia/Shanghai | -| `show time_zone` | show cli time zone | -| `set fetch_size=xxx` | set fetch size when querying data from server | -| `show fetch_size` | show fetch size | -| `set max_display_num=xxx` | set max lines for cli to output, -1 equals to unlimited | -| `help` | Get hints for CLI special commands | -| `exit/quit` | Exit CLI | - -### Note on using the CLI with OpenID Connect Auth enabled on Server side - -Openid connect (oidc) uses keycloack as the authority authentication service of oidc service - - -#### configuration - -The configuration is located in iotdb-system.properties , set the author_provider_class is org.apache.iotdb.commons.auth.authorizer.OpenIdAuthorizer Openid service is enabled, and the default value is org.apache.iotdb.db.auth.authorizer.LocalFileAuthorizer Indicates that the openid service is not enabled. - -``` -authorizer_provider_class=org.apache.iotdb.commons.auth.authorizer.OpenIdAuthorizer -``` - -If the openid service is turned on, openid_URL is required,openID_url value is http://ip:port/realms/{realmsName} - -``` -openID_url=http://127.0.0.1:8080/realms/iotdb/ -``` - -#### keycloack configuration - -1、Download the keycloack file (This tutorial is version 21.1.0) and start keycloack in keycloack/bin - -```shell -Shell >cd bin -Shell >./kc.sh start-dev -``` - -2、use url(https://ip:port) login keycloack, the first login needs to create a user -![avatar](/img/UserGuide/CLI/Command-Line-Interface/login_keycloak.png?raw=true) - -3、Click administration console -![avatar](/img/UserGuide/CLI/Command-Line-Interface/AdministrationConsole.png?raw=true) - -4、In the master menu on the left, click Create realm and enter Realm name to create a new realm -![avatar](/img/UserGuide/CLI/Command-Line-Interface/add_Realm_1.jpg?raw=true) - -![avatar](/img/UserGuide/CLI/Command-Line-Interface/add_Realm_2.jpg?raw=true) - - -5、Click the menu clients on the left to create clients - -![avatar](/img/UserGuide/CLI/Command-Line-Interface/client.jpg?raw=true) - -6、Click user on the left menu to create user - -![avatar](/img/UserGuide/CLI/Command-Line-Interface/user.jpg?raw=true) - -7、Click the newly created user ID, click the credentials navigation, enter the password and close the temporary option. The configuration of keycloud is completed - -![avatar](/img/UserGuide/CLI/Command-Line-Interface/pwd.jpg?raw=true) - -8、To create a role, click Roles on the left menu and then click the Create Role button to add a role - -![avatar](/img/UserGuide/CLI/Command-Line-Interface/add_role1.jpg?raw=true) - -9、 Enter `iotdb_admin` in the Role Name and click the save button. Tip: `iotdb_admin` here cannot be any other name, otherwise even after successful login, you will not have permission to use iotdb's query, insert, create database, add users, roles and other functions - -![avatar](/img/UserGuide/CLI/Command-Line-Interface/add_role2.jpg?raw=true) - -10、Click on the User menu on the left and then click on the user in the user list to add the `iotdb_admin` role we just created for that user - -![avatar](/img/UserGuide/CLI/Command-Line-Interface/add_role3.jpg?raw=true) - -11、 Select Role Mappings, select the `iotdb_admin` role in Assign Role - -![avatar](/img/UserGuide/CLI/Command-Line-Interface/add_role4.jpg?raw=true) - -![avatar](/img/UserGuide/CLI/Command-Line-Interface/add_role5.jpg?raw=true) - - -Tip: If the user role is adjusted, you need to regenerate the token and log in to iotdb again to take effect - -The above steps provide a way for keycloak to log into iotdb. For more ways, please refer to keycloak configuration - -If OIDC is enabled on server side then no username / passwort is needed but a valid Access Token from the OIDC Provider. -So as username you use the token and the password has to be empty, e.g. - -```shell -Shell > bash sbin/start-cli.sh -h 10.129.187.21 -p 6667 -u {my-access-token} -pw "" -``` - -Among them, you need to replace {my access token} (note, including {}) with your token, that is, the value corresponding to access_token. The password is empty and needs to be confirmed again. - -![avatar](/img/UserGuide/CLI/Command-Line-Interface/iotdbpw.jpeg?raw=true) - - -How to get the token is dependent on your OpenID Connect setup and not covered here. -In the simplest case you can get this via the command line with the `passwort-grant`. -For example, if you use keycloack as OIDC and you have a realm with a client `iotdb` defined as public you could use -the following `curl` command to fetch a token (replace all `{}` with appropriate values). - -```shell -curl -X POST "https://{your-keycloack-server}/realms/{your-realm}/protocol/openid-connect/token" \ - -H "Content-Type: application/x-www-form-urlencoded" \ - -d "username={username}" \ - -d "password={password}" \ - -d 'grant_type=password' \ - -d "client_id=iotdb-client" -``` - -The response looks something like - -```json -{"access_token":"eyJhbGciOiJSUzI1NiIsInR5cCIgOiAiSldUIiwia2lkIiA6ICJxMS1XbTBvelE1TzBtUUg4LVNKYXAyWmNONE1tdWNXd25RV0tZeFpKNG93In0.eyJleHAiOjE1OTAzOTgwNzEsImlhdCI6MTU5MDM5Nzc3MSwianRpIjoiNjA0ZmYxMDctN2NiNy00NTRmLWIwYmQtY2M2ZDQwMjFiNGU4IiwiaXNzIjoiaHR0cDovL2F1dGguZGVtby5wcmFnbWF0aWNpbmR1c3RyaWVzLmRlL2F1dGgvcmVhbG1zL0lvVERCIiwiYXVkIjoiYWNjb3VudCIsInN1YiI6ImJhMzJlNDcxLWM3NzItNGIzMy04ZGE2LTZmZThhY2RhMDA3MyIsInR5cCI6IkJlYXJlciIsImF6cCI6ImlvdGRiIiwic2Vzc2lvbl9zdGF0ZSI6IjA2MGQyODYyLTE0ZWQtNDJmZS1iYWY3LThkMWY3ODQ2NTdmMSIsImFjciI6IjEiLCJhbGxvd2VkLW9yaWdpbnMiOlsibG9jYWxob3N0OjgwODAiXSwicmVhbG1fYWNjZXNzIjp7InJvbGVzIjpbIm9mZmxpbmVfYWNjZXNzIiwidW1hX2F1dGhvcml6YXRpb24iLCJpb3RkYl9hZG1pbiJdfSwicmVzb3VyY2VfYWNjZXNzIjp7ImFjY291bnQiOnsicm9sZXMiOlsibWFuYWdlLWFjY291bnQiLCJtYW5hZ2UtYWNjb3VudC1saW5rcyIsInZpZXctcHJvZmlsZSJdfX0sInNjb3BlIjoiZW1haWwgcHJvZmlsZSIsImVtYWlsX3ZlcmlmaWVkIjp0cnVlLCJwcmVmZXJyZWRfdXNlcm5hbWUiOiJ1c2VyIn0.nwbrJkWdCNjzFrTDwKNuV5h9dDMg5ytRKGOXmFIajpfsbOutJytjWTCB2WpA8E1YI3KM6gU6Jx7cd7u0oPo5syHhfCz119n_wBiDnyTZkFOAPsx0M2z20kvBLN9k36_VfuCMFUeddJjO31MeLTmxB0UKg2VkxdczmzMH3pnalhxqpnWWk3GnrRrhAf2sZog0foH4Ae3Ks0lYtYzaWK_Yo7E4Px42-gJpohy3JevOC44aJ4auzJR1RBj9LUbgcRinkBy0JLi6XXiYznSC2V485CSBHW3sseXn7pSXQADhnmGQrLfFGO5ZljmPO18eFJaimdjvgSChsrlSEmTDDsoo5Q","expires_in":300,"refresh_expires_in":1800,"refresh_token":"eyJhbGciOiJIUzI1NiIsInR5cCIgOiAiSldUIiwia2lkIiA6ICJhMzZlMGU0NC02MWNmLTQ5NmMtOGRlZi03NTkwNjQ5MzQzMjEifQ.eyJleHAiOjE1OTAzOTk1NzEsImlhdCI6MTU5MDM5Nzc3MSwianRpIjoiNmMxNTBiY2EtYmE5NC00NTgxLWEwODEtYjI2YzhhMmI5YmZmIiwiaXNzIjoiaHR0cDovL2F1dGguZGVtby5wcmFnbWF0aWNpbmR1c3RyaWVzLmRlL2F1dGgvcmVhbG1zL0lvVERCIiwiYXVkIjoiaHR0cDovL2F1dGguZGVtby5wcmFnbWF0aWNpbmR1c3RyaWVzLmRlL2F1dGgvcmVhbG1zL0lvVERCIiwic3ViIjoiYmEzMmU0NzEtYzc3Mi00YjMzLThkYTYtNmZlOGFjZGEwMDczIiwidHlwIjoiUmVmcmVzaCIsImF6cCI6ImlvdGRiIiwic2Vzc2lvbl9zdGF0ZSI6IjA2MGQyODYyLTE0ZWQtNDJmZS1iYWY3LThkMWY3ODQ2NTdmMSIsInNjb3BlIjoiZW1haWwgcHJvZmlsZSJ9.ayNpXdNX28qahodX1zowrMGiUCw2AodlHBQFqr8Ui7c","token_type":"bearer","not-before-policy":0,"session_state":"060d2862-14ed-42fe-baf7-8d1f784657f1","scope":"email profile"} -``` - -The interesting part here is the access token with the key `access_token`. -This has to be passed as username (with parameter `-u`) and empty password to the CLI. - -### Batch Operation of Cli - --e parameter is designed for the Cli/shell tool in the situation where you would like to manipulate IoTDB in batches through scripts. By using the -e parameter, you can operate IoTDB without entering the cli's input mode. - -In order to avoid confusion between statements and other parameters, the current version only supports the -e parameter as the last parameter. - -The usage of -e parameter for Cli/shell is as follows: - -The Linux and MacOS system commands: - -```shell -Shell > bash sbin/start-cli.sh -h {host} -p {rpcPort} -u {user} -pw {password} -e {sql for iotdb} -``` - -The Windows system commands: - -```shell -Shell > sbin\start-cli.bat -h {host} -p {rpcPort} -u {user} -pw {password} -e {sql for iotdb} -``` - -In the Windows environment, the SQL statement of the -e parameter needs to use ` `` ` to replace `" "` - -In order to better explain the use of -e parameter, take following as an example(On linux system). - -Suppose you want to create a database root.demo to a newly launched IoTDB, create a timeseries root.demo.s1 and insert three data points into it. With -e parameter, you could write a shell like this: - -```shell -# !/bin/bash - -host=127.0.0.1 -rpcPort=6667 -user=root -pass=root - -bash ./sbin/start-cli.sh -h ${host} -p ${rpcPort} -u ${user} -pw ${pass} -e "create database root.demo" -bash ./sbin/start-cli.sh -h ${host} -p ${rpcPort} -u ${user} -pw ${pass} -e "create timeseries root.demo.s1 WITH DATATYPE=INT32, ENCODING=RLE" -bash ./sbin/start-cli.sh -h ${host} -p ${rpcPort} -u ${user} -pw ${pass} -e "insert into root.demo(timestamp,s1) values(1,10)" -bash ./sbin/start-cli.sh -h ${host} -p ${rpcPort} -u ${user} -pw ${pass} -e "insert into root.demo(timestamp,s1) values(2,11)" -bash ./sbin/start-cli.sh -h ${host} -p ${rpcPort} -u ${user} -pw ${pass} -e "insert into root.demo(timestamp,s1) values(3,12)" -bash ./sbin/start-cli.sh -h ${host} -p ${rpcPort} -u ${user} -pw ${pass} -e "select s1 from root.demo" -``` - -The results are shown in the figure, which are consistent with the Cli and jdbc operations. - -```shell - Shell > bash ./shell.sh -+-----------------------------+------------+ -| Time|root.demo.s1| -+-----------------------------+------------+ -|1970-01-01T08:00:00.001+08:00| 10| -|1970-01-01T08:00:00.002+08:00| 11| -|1970-01-01T08:00:00.003+08:00| 12| -+-----------------------------+------------+ -Total line number = 3 -It costs 0.267s -``` - -It should be noted that the use of the -e parameter in shell scripts requires attention to the escaping of special characters. +--> \ No newline at end of file diff --git a/src/UserGuide/dev-1.3/Tools-System/CLI_apache.md b/src/UserGuide/dev-1.3/Tools-System/CLI_apache.md new file mode 100644 index 000000000..47a038952 --- /dev/null +++ b/src/UserGuide/dev-1.3/Tools-System/CLI_apache.md @@ -0,0 +1,295 @@ + + +# Command Line Interface (CLI) + + +IoTDB provides Cli/shell tools for users to interact with IoTDB server in command lines. This document shows how Cli/shell tool works and the meaning of its parameters. + +> Note: In this document, \$IOTDB\_HOME represents the path of the IoTDB installation directory. + +## Installation + +If you use the source code version of IoTDB, then under the root path of IoTDB, execute: + +```shell +> mvn clean package -pl iotdb-client/cli -am -DskipTests -P get-jar-with-dependencies +``` + +After build, the IoTDB Cli will be in the folder "cli/target/iotdb-cli-{project.version}". + +If you download the binary version, then the Cli can be used directly in sbin folder. + +## Running + +### Running Cli + +After installation, there is a default user in IoTDB: `root`, and the +default password is `root`. Users can use this username to try IoTDB Cli/Shell tool. The cli startup script is the `start-cli` file under the \$IOTDB\_HOME/bin folder. When starting the script, you need to specify the IP and PORT. (Make sure the IoTDB cluster is running properly when you use Cli/Shell tool to connect to it.) + +Here is an example where the cluster is started locally and the user has not changed the running port. The default rpc port is +6667
+If you need to connect to the remote DataNode or changes +the rpc port number of the DataNode running, set the specific IP and RPC PORT at -h and -p.
+You also can set your own environment variable at the front of the start script ("/sbin/start-cli.sh" for linux and "/sbin/start-cli.bat" for windows) + +The Linux and MacOS system startup commands are as follows: + +```shell +Shell > bash sbin/start-cli.sh -h 127.0.0.1 -p 6667 -u root -pw root +``` + +The Windows system startup commands are as follows: + +```shell +Shell > sbin\start-cli.bat -h 127.0.0.1 -p 6667 -u root -pw root +``` + +After operating these commands, the cli can be started successfully. The successful status will be as follows: + +``` + _____ _________ ______ ______ +|_ _| | _ _ ||_ _ `.|_ _ \ + | | .--.|_/ | | \_| | | `. \ | |_) | + | | / .'`\ \ | | | | | | | __'. + _| |_| \__. | _| |_ _| |_.' /_| |__) | +|_____|'.__.' |_____| |______.'|_______/ version + + +Successfully login at 127.0.0.1:6667 +IoTDB> +``` + +Enter ```quit``` or `exit` can exit Cli. + +### Cli Parameters + +| Parameter name | Parameter type | Required | Description | Example | +| :--------------------------- | :------------------------- | :------- | :----------------------------------------------------------- | :------------------ | +| -disableISO8601 | No parameters | No | If this parameter is set, IoTDB will print the timestamp in digital form | -disableISO8601 | +| -h <`host`> | string, no quotation marks | Yes | The IP address of the IoTDB server | -h 10.129.187.21 | +| -help | No parameters | No | Print help information for IoTDB | -help | +| -p <`rpcPort`> | int | Yes | The rpc port number of the IoTDB server. IoTDB runs on rpc port 6667 by default | -p 6667 | +| -pw <`password`> | string, no quotation marks | No | The password used for IoTDB to connect to the server. If no password is entered, IoTDB will ask for password in Cli command | -pw root | +| -u <`username`> | string, no quotation marks | Yes | User name used for IoTDB to connect the server | -u root | +| -maxPRC <`maxPrintRowCount`> | int | No | Set the maximum number of rows that IoTDB returns | -maxPRC 10 | +| -e <`execute`> | string | No | manipulate IoTDB in batches without entering cli input mode | -e "show databases" | +| -c | empty | No | If the server enables `rpc_thrift_compression_enable=true`, then cli must use `-c` | -c | + +Following is a cli command which connects the host with IP +10.129.187.21, rpc port 6667, username "root", password "root", and prints the timestamp in digital form. The maximum number of lines displayed on the IoTDB command line is 10. + +The Linux and MacOS system startup commands are as follows: + +```shell +Shell > bash sbin/start-cli.sh -h 10.129.187.21 -p 6667 -u root -pw root -disableISO8601 -maxPRC 10 +``` + +The Windows system startup commands are as follows: + +```shell +Shell > sbin\start-cli.bat -h 10.129.187.21 -p 6667 -u root -pw root -disableISO8601 -maxPRC 10 +``` + +### CLI Special Command + +Special commands of Cli are below. + +| Command | Description / Example | +| :-------------------------- | :------------------------------------------------------ | +| `set time_display_type=xxx` | eg. long, default, ISO8601, yyyy-MM-dd HH:mm:ss | +| `show time_display_type` | show time display type | +| `set time_zone=xxx` | eg. +08:00, Asia/Shanghai | +| `show time_zone` | show cli time zone | +| `set fetch_size=xxx` | set fetch size when querying data from server | +| `show fetch_size` | show fetch size | +| `set max_display_num=xxx` | set max lines for cli to output, -1 equals to unlimited | +| `help` | Get hints for CLI special commands | +| `exit/quit` | Exit CLI | + +### Note on using the CLI with OpenID Connect Auth enabled on Server side + +Openid connect (oidc) uses keycloack as the authority authentication service of oidc service + + +#### configuration + +The configuration is located in iotdb-system.properties , set the author_provider_class is org.apache.iotdb.commons.auth.authorizer.OpenIdAuthorizer Openid service is enabled, and the default value is org.apache.iotdb.db.auth.authorizer.LocalFileAuthorizer Indicates that the openid service is not enabled. + +``` +authorizer_provider_class=org.apache.iotdb.commons.auth.authorizer.OpenIdAuthorizer +``` + +If the openid service is turned on, openid_URL is required,openID_url value is http://ip:port/realms/{realmsName} + +``` +openID_url=http://127.0.0.1:8080/realms/iotdb/ +``` + +#### keycloack configuration + +1、Download the keycloack file (This tutorial is version 21.1.0) and start keycloack in keycloack/bin + +```shell +Shell >cd bin +Shell >./kc.sh start-dev +``` + +2、use url(https://ip:port) login keycloack, the first login needs to create a user +![avatar](/img/UserGuide/CLI/Command-Line-Interface/login_keycloak.png?raw=true) + +3、Click administration console +![avatar](/img/UserGuide/CLI/Command-Line-Interface/AdministrationConsole.png?raw=true) + +4、In the master menu on the left, click Create realm and enter Realm name to create a new realm +![avatar](/img/UserGuide/CLI/Command-Line-Interface/add_Realm_1.jpg?raw=true) + +![avatar](/img/UserGuide/CLI/Command-Line-Interface/add_Realm_2.jpg?raw=true) + + +5、Click the menu clients on the left to create clients + +![avatar](/img/UserGuide/CLI/Command-Line-Interface/client.jpg?raw=true) + +6、Click user on the left menu to create user + +![avatar](/img/UserGuide/CLI/Command-Line-Interface/user.jpg?raw=true) + +7、Click the newly created user ID, click the credentials navigation, enter the password and close the temporary option. The configuration of keycloud is completed + +![avatar](/img/UserGuide/CLI/Command-Line-Interface/pwd.jpg?raw=true) + +8、To create a role, click Roles on the left menu and then click the Create Role button to add a role + +![avatar](/img/UserGuide/CLI/Command-Line-Interface/add_role1.jpg?raw=true) + +9、 Enter `iotdb_admin` in the Role Name and click the save button. Tip: `iotdb_admin` here cannot be any other name, otherwise even after successful login, you will not have permission to use iotdb's query, insert, create database, add users, roles and other functions + +![avatar](/img/UserGuide/CLI/Command-Line-Interface/add_role2.jpg?raw=true) + +10、Click on the User menu on the left and then click on the user in the user list to add the `iotdb_admin` role we just created for that user + +![avatar](/img/UserGuide/CLI/Command-Line-Interface/add_role3.jpg?raw=true) + +11、 Select Role Mappings, select the `iotdb_admin` role in Assign Role + +![avatar](/img/UserGuide/CLI/Command-Line-Interface/add_role4.jpg?raw=true) + +![avatar](/img/UserGuide/CLI/Command-Line-Interface/add_role5.jpg?raw=true) + + +Tip: If the user role is adjusted, you need to regenerate the token and log in to iotdb again to take effect + +The above steps provide a way for keycloak to log into iotdb. For more ways, please refer to keycloak configuration + +If OIDC is enabled on server side then no username / passwort is needed but a valid Access Token from the OIDC Provider. +So as username you use the token and the password has to be empty, e.g. + +```shell +Shell > bash sbin/start-cli.sh -h 10.129.187.21 -p 6667 -u {my-access-token} -pw "" +``` + +Among them, you need to replace {my access token} (note, including {}) with your token, that is, the value corresponding to access_token. The password is empty and needs to be confirmed again. + +![avatar](/img/UserGuide/CLI/Command-Line-Interface/iotdbpw.jpeg?raw=true) + + +How to get the token is dependent on your OpenID Connect setup and not covered here. +In the simplest case you can get this via the command line with the `passwort-grant`. +For example, if you use keycloack as OIDC and you have a realm with a client `iotdb` defined as public you could use +the following `curl` command to fetch a token (replace all `{}` with appropriate values). + +```shell +curl -X POST "https://{your-keycloack-server}/realms/{your-realm}/protocol/openid-connect/token" \ + -H "Content-Type: application/x-www-form-urlencoded" \ + -d "username={username}" \ + -d "password={password}" \ + -d 'grant_type=password' \ + -d "client_id=iotdb-client" +``` + +The response looks something like + +```json +{"access_token":"eyJhbGciOiJSUzI1NiIsInR5cCIgOiAiSldUIiwia2lkIiA6ICJxMS1XbTBvelE1TzBtUUg4LVNKYXAyWmNONE1tdWNXd25RV0tZeFpKNG93In0.eyJleHAiOjE1OTAzOTgwNzEsImlhdCI6MTU5MDM5Nzc3MSwianRpIjoiNjA0ZmYxMDctN2NiNy00NTRmLWIwYmQtY2M2ZDQwMjFiNGU4IiwiaXNzIjoiaHR0cDovL2F1dGguZGVtby5wcmFnbWF0aWNpbmR1c3RyaWVzLmRlL2F1dGgvcmVhbG1zL0lvVERCIiwiYXVkIjoiYWNjb3VudCIsInN1YiI6ImJhMzJlNDcxLWM3NzItNGIzMy04ZGE2LTZmZThhY2RhMDA3MyIsInR5cCI6IkJlYXJlciIsImF6cCI6ImlvdGRiIiwic2Vzc2lvbl9zdGF0ZSI6IjA2MGQyODYyLTE0ZWQtNDJmZS1iYWY3LThkMWY3ODQ2NTdmMSIsImFjciI6IjEiLCJhbGxvd2VkLW9yaWdpbnMiOlsibG9jYWxob3N0OjgwODAiXSwicmVhbG1fYWNjZXNzIjp7InJvbGVzIjpbIm9mZmxpbmVfYWNjZXNzIiwidW1hX2F1dGhvcml6YXRpb24iLCJpb3RkYl9hZG1pbiJdfSwicmVzb3VyY2VfYWNjZXNzIjp7ImFjY291bnQiOnsicm9sZXMiOlsibWFuYWdlLWFjY291bnQiLCJtYW5hZ2UtYWNjb3VudC1saW5rcyIsInZpZXctcHJvZmlsZSJdfX0sInNjb3BlIjoiZW1haWwgcHJvZmlsZSIsImVtYWlsX3ZlcmlmaWVkIjp0cnVlLCJwcmVmZXJyZWRfdXNlcm5hbWUiOiJ1c2VyIn0.nwbrJkWdCNjzFrTDwKNuV5h9dDMg5ytRKGOXmFIajpfsbOutJytjWTCB2WpA8E1YI3KM6gU6Jx7cd7u0oPo5syHhfCz119n_wBiDnyTZkFOAPsx0M2z20kvBLN9k36_VfuCMFUeddJjO31MeLTmxB0UKg2VkxdczmzMH3pnalhxqpnWWk3GnrRrhAf2sZog0foH4Ae3Ks0lYtYzaWK_Yo7E4Px42-gJpohy3JevOC44aJ4auzJR1RBj9LUbgcRinkBy0JLi6XXiYznSC2V485CSBHW3sseXn7pSXQADhnmGQrLfFGO5ZljmPO18eFJaimdjvgSChsrlSEmTDDsoo5Q","expires_in":300,"refresh_expires_in":1800,"refresh_token":"eyJhbGciOiJIUzI1NiIsInR5cCIgOiAiSldUIiwia2lkIiA6ICJhMzZlMGU0NC02MWNmLTQ5NmMtOGRlZi03NTkwNjQ5MzQzMjEifQ.eyJleHAiOjE1OTAzOTk1NzEsImlhdCI6MTU5MDM5Nzc3MSwianRpIjoiNmMxNTBiY2EtYmE5NC00NTgxLWEwODEtYjI2YzhhMmI5YmZmIiwiaXNzIjoiaHR0cDovL2F1dGguZGVtby5wcmFnbWF0aWNpbmR1c3RyaWVzLmRlL2F1dGgvcmVhbG1zL0lvVERCIiwiYXVkIjoiaHR0cDovL2F1dGguZGVtby5wcmFnbWF0aWNpbmR1c3RyaWVzLmRlL2F1dGgvcmVhbG1zL0lvVERCIiwic3ViIjoiYmEzMmU0NzEtYzc3Mi00YjMzLThkYTYtNmZlOGFjZGEwMDczIiwidHlwIjoiUmVmcmVzaCIsImF6cCI6ImlvdGRiIiwic2Vzc2lvbl9zdGF0ZSI6IjA2MGQyODYyLTE0ZWQtNDJmZS1iYWY3LThkMWY3ODQ2NTdmMSIsInNjb3BlIjoiZW1haWwgcHJvZmlsZSJ9.ayNpXdNX28qahodX1zowrMGiUCw2AodlHBQFqr8Ui7c","token_type":"bearer","not-before-policy":0,"session_state":"060d2862-14ed-42fe-baf7-8d1f784657f1","scope":"email profile"} +``` + +The interesting part here is the access token with the key `access_token`. +This has to be passed as username (with parameter `-u`) and empty password to the CLI. + +### Batch Operation of Cli + +-e parameter is designed for the Cli/shell tool in the situation where you would like to manipulate IoTDB in batches through scripts. By using the -e parameter, you can operate IoTDB without entering the cli's input mode. + +In order to avoid confusion between statements and other parameters, the current version only supports the -e parameter as the last parameter. + +The usage of -e parameter for Cli/shell is as follows: + +The Linux and MacOS system commands: + +```shell +Shell > bash sbin/start-cli.sh -h {host} -p {rpcPort} -u {user} -pw {password} -e {sql for iotdb} +``` + +The Windows system commands: + +```shell +Shell > sbin\start-cli.bat -h {host} -p {rpcPort} -u {user} -pw {password} -e {sql for iotdb} +``` + +In the Windows environment, the SQL statement of the -e parameter needs to use ` `` ` to replace `" "` + +In order to better explain the use of -e parameter, take following as an example(On linux system). + +Suppose you want to create a database root.demo to a newly launched IoTDB, create a timeseries root.demo.s1 and insert three data points into it. With -e parameter, you could write a shell like this: + +```shell +# !/bin/bash + +host=127.0.0.1 +rpcPort=6667 +user=root +pass=root + +bash ./sbin/start-cli.sh -h ${host} -p ${rpcPort} -u ${user} -pw ${pass} -e "create database root.demo" +bash ./sbin/start-cli.sh -h ${host} -p ${rpcPort} -u ${user} -pw ${pass} -e "create timeseries root.demo.s1 WITH DATATYPE=INT32, ENCODING=RLE" +bash ./sbin/start-cli.sh -h ${host} -p ${rpcPort} -u ${user} -pw ${pass} -e "insert into root.demo(timestamp,s1) values(1,10)" +bash ./sbin/start-cli.sh -h ${host} -p ${rpcPort} -u ${user} -pw ${pass} -e "insert into root.demo(timestamp,s1) values(2,11)" +bash ./sbin/start-cli.sh -h ${host} -p ${rpcPort} -u ${user} -pw ${pass} -e "insert into root.demo(timestamp,s1) values(3,12)" +bash ./sbin/start-cli.sh -h ${host} -p ${rpcPort} -u ${user} -pw ${pass} -e "select s1 from root.demo" +``` + +The results are shown in the figure, which are consistent with the Cli and jdbc operations. + +```shell + Shell > bash ./shell.sh ++-----------------------------+------------+ +| Time|root.demo.s1| ++-----------------------------+------------+ +|1970-01-01T08:00:00.001+08:00| 10| +|1970-01-01T08:00:00.002+08:00| 11| +|1970-01-01T08:00:00.003+08:00| 12| ++-----------------------------+------------+ +Total line number = 3 +It costs 0.267s +``` + +It should be noted that the use of the -e parameter in shell scripts requires attention to the escaping of special characters. diff --git a/src/UserGuide/dev-1.3/Tools-System/CLI_timecho.md b/src/UserGuide/dev-1.3/Tools-System/CLI_timecho.md new file mode 100644 index 000000000..dfc5fdc56 --- /dev/null +++ b/src/UserGuide/dev-1.3/Tools-System/CLI_timecho.md @@ -0,0 +1,281 @@ + + +# Command Line Interface (CLI) + + +IoTDB provides Cli/shell tools for users to interact with IoTDB server in command lines. This document shows how Cli/shell tool works and the meaning of its parameters. + +> Note: In this document, \$IOTDB\_HOME represents the path of the IoTDB installation directory. + +## Running Cli + +After installation, there is a default user in IoTDB: `root`, and the +default password is `root`. Users can use this username to try IoTDB Cli/Shell tool. The cli startup script is the `start-cli` file under the \$IOTDB\_HOME/bin folder. When starting the script, you need to specify the IP and PORT. (Make sure the IoTDB cluster is running properly when you use Cli/Shell tool to connect to it.) + +Here is an example where the cluster is started locally and the user has not changed the running port. The default rpc port is +6667
+If you need to connect to the remote DataNode or changes +the rpc port number of the DataNode running, set the specific IP and RPC PORT at -h and -p.
+You also can set your own environment variable at the front of the start script ("/sbin/start-cli.sh" for linux and "/sbin/start-cli.bat" for windows) + +The Linux and MacOS system startup commands are as follows: + +```shell +Shell > bash sbin/start-cli.sh -h 127.0.0.1 -p 6667 -u root -pw root +``` + +The Windows system startup commands are as follows: + +```shell +Shell > sbin\start-cli.bat -h 127.0.0.1 -p 6667 -u root -pw root +``` + +After operating these commands, the cli can be started successfully. The successful status will be as follows: + +``` + _____ _________ ______ ______ +|_ _| | _ _ ||_ _ `.|_ _ \ + | | .--.|_/ | | \_| | | `. \ | |_) | + | | / .'`\ \ | | | | | | | __'. + _| |_| \__. | _| |_ _| |_.' /_| |__) | +|_____|'.__.' |_____| |______.'|_______/ version + + +Successfully login at 127.0.0.1:6667 +IoTDB> +``` + +Enter ```quit``` or `exit` can exit Cli. + +## Cli Parameters + +| Parameter name | Parameter type | Required | Description | Example | +| :--------------------------- | :------------------------- | :------- | :----------------------------------------------------------- | :------------------ | +| -disableISO8601 | No parameters | No | If this parameter is set, IoTDB will print the timestamp in digital form | -disableISO8601 | +| -h <`host`> | string, no quotation marks | Yes | The IP address of the IoTDB server | -h 10.129.187.21 | +| -help | No parameters | No | Print help information for IoTDB | -help | +| -p <`rpcPort`> | int | Yes | The rpc port number of the IoTDB server. IoTDB runs on rpc port 6667 by default | -p 6667 | +| -pw <`password`> | string, no quotation marks | No | The password used for IoTDB to connect to the server. If no password is entered, IoTDB will ask for password in Cli command | -pw root | +| -u <`username`> | string, no quotation marks | Yes | User name used for IoTDB to connect the server | -u root | +| -maxPRC <`maxPrintRowCount`> | int | No | Set the maximum number of rows that IoTDB returns | -maxPRC 10 | +| -e <`execute`> | string | No | manipulate IoTDB in batches without entering cli input mode | -e "show databases" | +| -c | empty | No | If the server enables `rpc_thrift_compression_enable=true`, then cli must use `-c` | -c | + +Following is a cli command which connects the host with IP +10.129.187.21, rpc port 6667, username "root", password "root", and prints the timestamp in digital form. The maximum number of lines displayed on the IoTDB command line is 10. + +The Linux and MacOS system startup commands are as follows: + +```shell +Shell > bash sbin/start-cli.sh -h 10.129.187.21 -p 6667 -u root -pw root -disableISO8601 -maxPRC 10 +``` + +The Windows system startup commands are as follows: + +```shell +Shell > sbin\start-cli.bat -h 10.129.187.21 -p 6667 -u root -pw root -disableISO8601 -maxPRC 10 +``` + +## CLI Special Command + +Special commands of Cli are below. + +| Command | Description / Example | +| :-------------------------- | :------------------------------------------------------ | +| `set time_display_type=xxx` | eg. long, default, ISO8601, yyyy-MM-dd HH:mm:ss | +| `show time_display_type` | show time display type | +| `set time_zone=xxx` | eg. +08:00, Asia/Shanghai | +| `show time_zone` | show cli time zone | +| `set fetch_size=xxx` | set fetch size when querying data from server | +| `show fetch_size` | show fetch size | +| `set max_display_num=xxx` | set max lines for cli to output, -1 equals to unlimited | +| `help` | Get hints for CLI special commands | +| `exit/quit` | Exit CLI | + +## Note on using the CLI with OpenID Connect Auth enabled on Server side + +Openid connect (oidc) uses keycloack as the authority authentication service of oidc service + + +### configuration + +The configuration is located in iotdb-system.properties , set the author_provider_class is org.apache.iotdb.commons.auth.authorizer.OpenIdAuthorizer Openid service is enabled, and the default value is org.apache.iotdb.db.auth.authorizer.LocalFileAuthorizer Indicates that the openid service is not enabled. + +``` +authorizer_provider_class=org.apache.iotdb.commons.auth.authorizer.OpenIdAuthorizer +``` + +If the openid service is turned on, openid_URL is required,openID_url value is http://ip:port/realms/{realmsName} + +``` +openID_url=http://127.0.0.1:8080/realms/iotdb/ +``` + +### keycloack configuration + +1、Download the keycloack file (This tutorial is version 21.1.0) and start keycloack in keycloack/bin + +```shell +Shell >cd bin +Shell >./kc.sh start-dev +``` + +2、use url(https://ip:port) login keycloack, the first login needs to create a user +![avatar](/img/UserGuide/CLI/Command-Line-Interface/login_keycloak.png?raw=true) + +3、Click administration console +![avatar](/img/UserGuide/CLI/Command-Line-Interface/AdministrationConsole.png?raw=true) + +4、In the master menu on the left, click Create realm and enter Realm name to create a new realm +![avatar](/img/UserGuide/CLI/Command-Line-Interface/add_Realm_1.jpg?raw=true) + +![avatar](/img/UserGuide/CLI/Command-Line-Interface/add_Realm_2.jpg?raw=true) + + +5、Click the menu clients on the left to create clients + +![avatar](/img/UserGuide/CLI/Command-Line-Interface/client.jpg?raw=true) + +6、Click user on the left menu to create user + +![avatar](/img/UserGuide/CLI/Command-Line-Interface/user.jpg?raw=true) + +7、Click the newly created user ID, click the credentials navigation, enter the password and close the temporary option. The configuration of keycloud is completed + +![avatar](/img/UserGuide/CLI/Command-Line-Interface/pwd.jpg?raw=true) + +8、To create a role, click Roles on the left menu and then click the Create Role button to add a role + +![avatar](/img/UserGuide/CLI/Command-Line-Interface/add_role1.jpg?raw=true) + +9、 Enter `iotdb_admin` in the Role Name and click the save button. Tip: `iotdb_admin` here cannot be any other name, otherwise even after successful login, you will not have permission to use iotdb's query, insert, create database, add users, roles and other functions + +![avatar](/img/UserGuide/CLI/Command-Line-Interface/add_role2.jpg?raw=true) + +10、Click on the User menu on the left and then click on the user in the user list to add the `iotdb_admin` role we just created for that user + +![avatar](/img/UserGuide/CLI/Command-Line-Interface/add_role3.jpg?raw=true) + +11、 Select Role Mappings, select the `iotdb_admin` role in Assign Role + +![avatar](/img/UserGuide/CLI/Command-Line-Interface/add_role4.jpg?raw=true) + +![avatar](/img/UserGuide/CLI/Command-Line-Interface/add_role5.jpg?raw=true) + + +Tip: If the user role is adjusted, you need to regenerate the token and log in to iotdb again to take effect + +The above steps provide a way for keycloak to log into iotdb. For more ways, please refer to keycloak configuration + +If OIDC is enabled on server side then no username / passwort is needed but a valid Access Token from the OIDC Provider. +So as username you use the token and the password has to be empty, e.g. + +```shell +Shell > bash sbin/start-cli.sh -h 10.129.187.21 -p 6667 -u {my-access-token} -pw "" +``` + +Among them, you need to replace {my access token} (note, including {}) with your token, that is, the value corresponding to access_token. The password is empty and needs to be confirmed again. + +![avatar](/img/UserGuide/CLI/Command-Line-Interface/iotdbpw.jpeg?raw=true) + + +How to get the token is dependent on your OpenID Connect setup and not covered here. +In the simplest case you can get this via the command line with the `passwort-grant`. +For example, if you use keycloack as OIDC and you have a realm with a client `iotdb` defined as public you could use +the following `curl` command to fetch a token (replace all `{}` with appropriate values). + +```shell +curl -X POST "https://{your-keycloack-server}/realms/{your-realm}/protocol/openid-connect/token" \ + -H "Content-Type: application/x-www-form-urlencoded" \ + -d "username={username}" \ + -d "password={password}" \ + -d 'grant_type=password' \ + -d "client_id=iotdb-client" +``` + +The response looks something like + +```json +{"access_token":"eyJhbGciOiJSUzI1NiIsInR5cCIgOiAiSldUIiwia2lkIiA6ICJxMS1XbTBvelE1TzBtUUg4LVNKYXAyWmNONE1tdWNXd25RV0tZeFpKNG93In0.eyJleHAiOjE1OTAzOTgwNzEsImlhdCI6MTU5MDM5Nzc3MSwianRpIjoiNjA0ZmYxMDctN2NiNy00NTRmLWIwYmQtY2M2ZDQwMjFiNGU4IiwiaXNzIjoiaHR0cDovL2F1dGguZGVtby5wcmFnbWF0aWNpbmR1c3RyaWVzLmRlL2F1dGgvcmVhbG1zL0lvVERCIiwiYXVkIjoiYWNjb3VudCIsInN1YiI6ImJhMzJlNDcxLWM3NzItNGIzMy04ZGE2LTZmZThhY2RhMDA3MyIsInR5cCI6IkJlYXJlciIsImF6cCI6ImlvdGRiIiwic2Vzc2lvbl9zdGF0ZSI6IjA2MGQyODYyLTE0ZWQtNDJmZS1iYWY3LThkMWY3ODQ2NTdmMSIsImFjciI6IjEiLCJhbGxvd2VkLW9yaWdpbnMiOlsibG9jYWxob3N0OjgwODAiXSwicmVhbG1fYWNjZXNzIjp7InJvbGVzIjpbIm9mZmxpbmVfYWNjZXNzIiwidW1hX2F1dGhvcml6YXRpb24iLCJpb3RkYl9hZG1pbiJdfSwicmVzb3VyY2VfYWNjZXNzIjp7ImFjY291bnQiOnsicm9sZXMiOlsibWFuYWdlLWFjY291bnQiLCJtYW5hZ2UtYWNjb3VudC1saW5rcyIsInZpZXctcHJvZmlsZSJdfX0sInNjb3BlIjoiZW1haWwgcHJvZmlsZSIsImVtYWlsX3ZlcmlmaWVkIjp0cnVlLCJwcmVmZXJyZWRfdXNlcm5hbWUiOiJ1c2VyIn0.nwbrJkWdCNjzFrTDwKNuV5h9dDMg5ytRKGOXmFIajpfsbOutJytjWTCB2WpA8E1YI3KM6gU6Jx7cd7u0oPo5syHhfCz119n_wBiDnyTZkFOAPsx0M2z20kvBLN9k36_VfuCMFUeddJjO31MeLTmxB0UKg2VkxdczmzMH3pnalhxqpnWWk3GnrRrhAf2sZog0foH4Ae3Ks0lYtYzaWK_Yo7E4Px42-gJpohy3JevOC44aJ4auzJR1RBj9LUbgcRinkBy0JLi6XXiYznSC2V485CSBHW3sseXn7pSXQADhnmGQrLfFGO5ZljmPO18eFJaimdjvgSChsrlSEmTDDsoo5Q","expires_in":300,"refresh_expires_in":1800,"refresh_token":"eyJhbGciOiJIUzI1NiIsInR5cCIgOiAiSldUIiwia2lkIiA6ICJhMzZlMGU0NC02MWNmLTQ5NmMtOGRlZi03NTkwNjQ5MzQzMjEifQ.eyJleHAiOjE1OTAzOTk1NzEsImlhdCI6MTU5MDM5Nzc3MSwianRpIjoiNmMxNTBiY2EtYmE5NC00NTgxLWEwODEtYjI2YzhhMmI5YmZmIiwiaXNzIjoiaHR0cDovL2F1dGguZGVtby5wcmFnbWF0aWNpbmR1c3RyaWVzLmRlL2F1dGgvcmVhbG1zL0lvVERCIiwiYXVkIjoiaHR0cDovL2F1dGguZGVtby5wcmFnbWF0aWNpbmR1c3RyaWVzLmRlL2F1dGgvcmVhbG1zL0lvVERCIiwic3ViIjoiYmEzMmU0NzEtYzc3Mi00YjMzLThkYTYtNmZlOGFjZGEwMDczIiwidHlwIjoiUmVmcmVzaCIsImF6cCI6ImlvdGRiIiwic2Vzc2lvbl9zdGF0ZSI6IjA2MGQyODYyLTE0ZWQtNDJmZS1iYWY3LThkMWY3ODQ2NTdmMSIsInNjb3BlIjoiZW1haWwgcHJvZmlsZSJ9.ayNpXdNX28qahodX1zowrMGiUCw2AodlHBQFqr8Ui7c","token_type":"bearer","not-before-policy":0,"session_state":"060d2862-14ed-42fe-baf7-8d1f784657f1","scope":"email profile"} +``` + +The interesting part here is the access token with the key `access_token`. +This has to be passed as username (with parameter `-u`) and empty password to the CLI. + +## Batch Operation of Cli + +-e parameter is designed for the Cli/shell tool in the situation where you would like to manipulate IoTDB in batches through scripts. By using the -e parameter, you can operate IoTDB without entering the cli's input mode. + +In order to avoid confusion between statements and other parameters, the current version only supports the -e parameter as the last parameter. + +The usage of -e parameter for Cli/shell is as follows: + +The Linux and MacOS system commands: + +```shell +Shell > bash sbin/start-cli.sh -h {host} -p {rpcPort} -u {user} -pw {password} -e {sql for iotdb} +``` + +The Windows system commands: + +```shell +Shell > sbin\start-cli.bat -h {host} -p {rpcPort} -u {user} -pw {password} -e {sql for iotdb} +``` + +In the Windows environment, the SQL statement of the -e parameter needs to use ` `` ` to replace `" "` + +In order to better explain the use of -e parameter, take following as an example(On linux system). + +Suppose you want to create a database root.demo to a newly launched IoTDB, create a timeseries root.demo.s1 and insert three data points into it. With -e parameter, you could write a shell like this: + +```shell +# !/bin/bash + +host=127.0.0.1 +rpcPort=6667 +user=root +pass=root + +bash ./sbin/start-cli.sh -h ${host} -p ${rpcPort} -u ${user} -pw ${pass} -e "create database root.demo" +bash ./sbin/start-cli.sh -h ${host} -p ${rpcPort} -u ${user} -pw ${pass} -e "create timeseries root.demo.s1 WITH DATATYPE=INT32, ENCODING=RLE" +bash ./sbin/start-cli.sh -h ${host} -p ${rpcPort} -u ${user} -pw ${pass} -e "insert into root.demo(timestamp,s1) values(1,10)" +bash ./sbin/start-cli.sh -h ${host} -p ${rpcPort} -u ${user} -pw ${pass} -e "insert into root.demo(timestamp,s1) values(2,11)" +bash ./sbin/start-cli.sh -h ${host} -p ${rpcPort} -u ${user} -pw ${pass} -e "insert into root.demo(timestamp,s1) values(3,12)" +bash ./sbin/start-cli.sh -h ${host} -p ${rpcPort} -u ${user} -pw ${pass} -e "select s1 from root.demo" +``` + +The results are shown in the figure, which are consistent with the Cli and jdbc operations. + +```shell + Shell > bash ./shell.sh ++-----------------------------+------------+ +| Time|root.demo.s1| ++-----------------------------+------------+ +|1970-01-01T08:00:00.001+08:00| 10| +|1970-01-01T08:00:00.002+08:00| 11| +|1970-01-01T08:00:00.003+08:00| 12| ++-----------------------------+------------+ +Total line number = 3 +It costs 0.267s +``` + +It should be noted that the use of the -e parameter in shell scripts requires attention to the escaping of special characters. diff --git a/src/UserGuide/latest/Tools-System/CLI.md b/src/UserGuide/latest/Tools-System/CLI.md index 665af2052..03580fafb 100644 --- a/src/UserGuide/latest/Tools-System/CLI.md +++ b/src/UserGuide/latest/Tools-System/CLI.md @@ -1,3 +1,6 @@ +--- +redirectTo: CLI_apache.html +--- - -# Command Line Interface (CLI) - - -IoTDB provides Cli/shell tools for users to interact with IoTDB server in command lines. This document shows how Cli/shell tool works and the meaning of its parameters. - -> Note: In this document, \$IOTDB\_HOME represents the path of the IoTDB installation directory. - -## 1. Installation - -If you use the source code version of IoTDB, then under the root path of IoTDB, execute: - -```shell -> mvn clean package -pl iotdb-client/cli -am -DskipTests -P get-jar-with-dependencies -``` - -After build, the IoTDB Cli will be in the folder "cli/target/iotdb-cli-{project.version}". - -If you download the binary version, then the Cli can be used directly in sbin folder. - -## 2. Running - -### 2.1 Running Cli - -After installation, there is a default user in IoTDB: `root`, and the -default password is `root`. Users can use this username to try IoTDB Cli/Shell tool. The cli startup script is the `start-cli` file under the \$IOTDB\_HOME/bin folder. When starting the script, you need to specify the IP and PORT. (Make sure the IoTDB cluster is running properly when you use Cli/Shell tool to connect to it.) - -Here is an example where the cluster is started locally and the user has not changed the running port. The default rpc port is -6667
-If you need to connect to the remote DataNode or changes -the rpc port number of the DataNode running, set the specific IP and RPC PORT at -h and -p.
-You also can set your own environment variable at the front of the start script - -The Linux and MacOS system startup commands are as follows: - -```shell -Shell > bash sbin/start-cli.sh -h 127.0.0.1 -p 6667 -u root -pw root -``` - -The Windows system startup commands are as follows: - -```shell -# Before version V2.0.4.x -Shell > sbin\start-cli.bat -h 127.0.0.1 -p 6667 -u root -pw root - -# V2.0.4.x and later versions -Shell > sbin\windows\start-cli.bat -h 127.0.0.1 -p 6667 -u root -pw root -``` - -After operating these commands, the cli can be started successfully. The successful status will be as follows: - -``` - _____ _________ ______ ______ -|_ _| | _ _ ||_ _ `.|_ _ \ - | | .--.|_/ | | \_| | | `. \ | |_) | - | | / .'`\ \ | | | | | | | __'. - _| |_| \__. | _| |_ _| |_.' /_| |__) | -|_____|'.__.' |_____| |______.'|_______/ version - - -Successfully login at 127.0.0.1:6667 -IoTDB> -``` - -Enter ```quit``` or `exit` can exit Cli. - -### 2.2 Cli Parameters - -| Parameter name | Parameter type | Required | Description | Example | -| :--------------------------- | :------------------------- | :------- | :----------------------------------------------------------- | :------------------ | -| -disableISO8601 | No parameters | No | If this parameter is set, IoTDB will print the timestamp in digital form | -disableISO8601 | -| -h <`host`> | string, no quotation marks | Yes | The IP address of the IoTDB server | -h 10.129.187.21 | -| -help | No parameters | No | Print help information for IoTDB | -help | -| -p <`rpcPort`> | int | Yes | The rpc port number of the IoTDB server. IoTDB runs on rpc port 6667 by default | -p 6667 | -| -pw <`password`> | string, no quotation marks | No | The password used for IoTDB to connect to the server. If no password is entered, IoTDB will ask for password in Cli command | -pw root | -| -u <`username`> | string, no quotation marks | Yes | User name used for IoTDB to connect the server | -u root | -| -maxPRC <`maxPrintRowCount`> | int | No | Set the maximum number of rows that IoTDB returns | -maxPRC 10 | -| -e <`execute`> | string | No | manipulate IoTDB in batches without entering cli input mode | -e "show databases" | -| -c | empty | No | If the server enables `rpc_thrift_compression_enable=true`, then cli must use `-c` | -c | - -Following is a cli command which connects the host with IP -10.129.187.21, rpc port 6667, username "root", password "root", and prints the timestamp in digital form. The maximum number of lines displayed on the IoTDB command line is 10. - -The Linux and MacOS system startup commands are as follows: - -```shell -Shell > bash sbin/start-cli.sh -h 10.129.187.21 -p 6667 -u root -pw root -disableISO8601 -maxPRC 10 -``` - -The Windows system startup commands are as follows: - -```shell -# Before version V2.0.4.x -Shell > sbin\start-cli.bat -h 10.129.187.21 -p 6667 -u root -pw root -disableISO8601 -maxPRC 10 - -# # V2.0.4.x and later versions -Shell > sbin\windows\start-cli.bat -h 10.129.187.21 -p 6667 -u root -pw root -disableISO8601 -maxPRC 10 -``` - -### 2.3 CLI Special Command - -Special commands of Cli are below. - -| Command | Description / Example | -| :-------------------------- | :------------------------------------------------------ | -| `set time_display_type=xxx` | eg. long, default, ISO8601, yyyy-MM-dd HH:mm:ss | -| `show time_display_type` | show time display type | -| `set time_zone=xxx` | eg. +08:00, Asia/Shanghai | -| `show time_zone` | show cli time zone | -| `set fetch_size=xxx` | set fetch size when querying data from server | -| `show fetch_size` | show fetch size | -| `set max_display_num=xxx` | set max lines for cli to output, -1 equals to unlimited | -| `help` | Get hints for CLI special commands | -| `exit/quit` | Exit CLI | - -### 2.4 Note on using the CLI with OpenID Connect Auth enabled on Server side - -Openid connect (oidc) uses keycloack as the authority authentication service of oidc service - - -#### configuration - -The configuration is located in iotdb-system.properties , set the author_provider_class is org.apache.iotdb.commons.auth.authorizer.OpenIdAuthorizer Openid service is enabled, and the default value is org.apache.iotdb.db.auth.authorizer.LocalFileAuthorizer Indicates that the openid service is not enabled. - -``` -authorizer_provider_class=org.apache.iotdb.commons.auth.authorizer.OpenIdAuthorizer -``` - -If the openid service is turned on, openid_URL is required,openID_url value is http://ip:port/realms/{realmsName} - -``` -openID_url=http://127.0.0.1:8080/realms/iotdb/ -``` - -#### keycloack configuration - -1、Download the keycloack file (This tutorial is version 21.1.0) and start keycloack in keycloack/bin - -```shell -Shell >cd bin -Shell >./kc.sh start-dev -``` - -2、use url(https://ip:port) login keycloack, the first login needs to create a user -![avatar](/img/UserGuide/CLI/Command-Line-Interface/login_keycloak.png?raw=true) - -3、Click administration console -![avatar](/img/UserGuide/CLI/Command-Line-Interface/AdministrationConsole.png?raw=true) - -4、In the master menu on the left, click Create realm and enter Realm name to create a new realm -![avatar](/img/UserGuide/CLI/Command-Line-Interface/add_Realm_1.jpg?raw=true) - -![avatar](/img/UserGuide/CLI/Command-Line-Interface/add_Realm_2.jpg?raw=true) - - -5、Click the menu clients on the left to create clients - -![avatar](/img/UserGuide/CLI/Command-Line-Interface/client.jpg?raw=true) - -6、Click user on the left menu to create user - -![avatar](/img/UserGuide/CLI/Command-Line-Interface/user.jpg?raw=true) - -7、Click the newly created user ID, click the credentials navigation, enter the password and close the temporary option. The configuration of keycloud is completed - -![avatar](/img/UserGuide/CLI/Command-Line-Interface/pwd.jpg?raw=true) - -8、To create a role, click Roles on the left menu and then click the Create Role button to add a role - -![avatar](/img/UserGuide/CLI/Command-Line-Interface/add_role1.jpg?raw=true) - -9、 Enter `iotdb_admin` in the Role Name and click the save button. Tip: `iotdb_admin` here cannot be any other name, otherwise even after successful login, you will not have permission to use iotdb's query, insert, create database, add users, roles and other functions - -![avatar](/img/UserGuide/CLI/Command-Line-Interface/add_role2.jpg?raw=true) - -10、Click on the User menu on the left and then click on the user in the user list to add the `iotdb_admin` role we just created for that user - -![avatar](/img/UserGuide/CLI/Command-Line-Interface/add_role3.jpg?raw=true) - -11、 Select Role Mappings, select the `iotdb_admin` role in Assign Role - -![avatar](/img/UserGuide/CLI/Command-Line-Interface/add_role4.jpg?raw=true) - -![avatar](/img/UserGuide/CLI/Command-Line-Interface/add_role5.jpg?raw=true) - - -Tip: If the user role is adjusted, you need to regenerate the token and log in to iotdb again to take effect - -The above steps provide a way for keycloak to log into iotdb. For more ways, please refer to keycloak configuration - -If OIDC is enabled on server side then no username / passwort is needed but a valid Access Token from the OIDC Provider. -So as username you use the token and the password has to be empty, e.g. - -```shell -Shell > bash sbin/start-cli.sh -h 10.129.187.21 -p 6667 -u {my-access-token} -pw "" -``` - -Among them, you need to replace {my access token} (note, including {}) with your token, that is, the value corresponding to access_token. The password is empty and needs to be confirmed again. - -![avatar](/img/UserGuide/CLI/Command-Line-Interface/iotdbpw.jpeg?raw=true) - - -How to get the token is dependent on your OpenID Connect setup and not covered here. -In the simplest case you can get this via the command line with the `passwort-grant`. -For example, if you use keycloack as OIDC and you have a realm with a client `iotdb` defined as public you could use -the following `curl` command to fetch a token (replace all `{}` with appropriate values). - -```shell -curl -X POST "https://{your-keycloack-server}/realms/{your-realm}/protocol/openid-connect/token" \ - -H "Content-Type: application/x-www-form-urlencoded" \ - -d "username={username}" \ - -d "password={password}" \ - -d 'grant_type=password' \ - -d "client_id=iotdb-client" -``` - -The response looks something like - -```json -{"access_token":"eyJhbGciOiJSUzI1NiIsInR5cCIgOiAiSldUIiwia2lkIiA6ICJxMS1XbTBvelE1TzBtUUg4LVNKYXAyWmNONE1tdWNXd25RV0tZeFpKNG93In0.eyJleHAiOjE1OTAzOTgwNzEsImlhdCI6MTU5MDM5Nzc3MSwianRpIjoiNjA0ZmYxMDctN2NiNy00NTRmLWIwYmQtY2M2ZDQwMjFiNGU4IiwiaXNzIjoiaHR0cDovL2F1dGguZGVtby5wcmFnbWF0aWNpbmR1c3RyaWVzLmRlL2F1dGgvcmVhbG1zL0lvVERCIiwiYXVkIjoiYWNjb3VudCIsInN1YiI6ImJhMzJlNDcxLWM3NzItNGIzMy04ZGE2LTZmZThhY2RhMDA3MyIsInR5cCI6IkJlYXJlciIsImF6cCI6ImlvdGRiIiwic2Vzc2lvbl9zdGF0ZSI6IjA2MGQyODYyLTE0ZWQtNDJmZS1iYWY3LThkMWY3ODQ2NTdmMSIsImFjciI6IjEiLCJhbGxvd2VkLW9yaWdpbnMiOlsibG9jYWxob3N0OjgwODAiXSwicmVhbG1fYWNjZXNzIjp7InJvbGVzIjpbIm9mZmxpbmVfYWNjZXNzIiwidW1hX2F1dGhvcml6YXRpb24iLCJpb3RkYl9hZG1pbiJdfSwicmVzb3VyY2VfYWNjZXNzIjp7ImFjY291bnQiOnsicm9sZXMiOlsibWFuYWdlLWFjY291bnQiLCJtYW5hZ2UtYWNjb3VudC1saW5rcyIsInZpZXctcHJvZmlsZSJdfX0sInNjb3BlIjoiZW1haWwgcHJvZmlsZSIsImVtYWlsX3ZlcmlmaWVkIjp0cnVlLCJwcmVmZXJyZWRfdXNlcm5hbWUiOiJ1c2VyIn0.nwbrJkWdCNjzFrTDwKNuV5h9dDMg5ytRKGOXmFIajpfsbOutJytjWTCB2WpA8E1YI3KM6gU6Jx7cd7u0oPo5syHhfCz119n_wBiDnyTZkFOAPsx0M2z20kvBLN9k36_VfuCMFUeddJjO31MeLTmxB0UKg2VkxdczmzMH3pnalhxqpnWWk3GnrRrhAf2sZog0foH4Ae3Ks0lYtYzaWK_Yo7E4Px42-gJpohy3JevOC44aJ4auzJR1RBj9LUbgcRinkBy0JLi6XXiYznSC2V485CSBHW3sseXn7pSXQADhnmGQrLfFGO5ZljmPO18eFJaimdjvgSChsrlSEmTDDsoo5Q","expires_in":300,"refresh_expires_in":1800,"refresh_token":"eyJhbGciOiJIUzI1NiIsInR5cCIgOiAiSldUIiwia2lkIiA6ICJhMzZlMGU0NC02MWNmLTQ5NmMtOGRlZi03NTkwNjQ5MzQzMjEifQ.eyJleHAiOjE1OTAzOTk1NzEsImlhdCI6MTU5MDM5Nzc3MSwianRpIjoiNmMxNTBiY2EtYmE5NC00NTgxLWEwODEtYjI2YzhhMmI5YmZmIiwiaXNzIjoiaHR0cDovL2F1dGguZGVtby5wcmFnbWF0aWNpbmR1c3RyaWVzLmRlL2F1dGgvcmVhbG1zL0lvVERCIiwiYXVkIjoiaHR0cDovL2F1dGguZGVtby5wcmFnbWF0aWNpbmR1c3RyaWVzLmRlL2F1dGgvcmVhbG1zL0lvVERCIiwic3ViIjoiYmEzMmU0NzEtYzc3Mi00YjMzLThkYTYtNmZlOGFjZGEwMDczIiwidHlwIjoiUmVmcmVzaCIsImF6cCI6ImlvdGRiIiwic2Vzc2lvbl9zdGF0ZSI6IjA2MGQyODYyLTE0ZWQtNDJmZS1iYWY3LThkMWY3ODQ2NTdmMSIsInNjb3BlIjoiZW1haWwgcHJvZmlsZSJ9.ayNpXdNX28qahodX1zowrMGiUCw2AodlHBQFqr8Ui7c","token_type":"bearer","not-before-policy":0,"session_state":"060d2862-14ed-42fe-baf7-8d1f784657f1","scope":"email profile"} -``` - -The interesting part here is the access token with the key `access_token`. -This has to be passed as username (with parameter `-u`) and empty password to the CLI. - -### 2.5 Batch Operation of Cli - --e parameter is designed for the Cli/shell tool in the situation where you would like to manipulate IoTDB in batches through scripts. By using the -e parameter, you can operate IoTDB without entering the cli's input mode. - -In order to avoid confusion between statements and other parameters, the current version only supports the -e parameter as the last parameter. - -The usage of -e parameter for Cli/shell is as follows: - -The Linux and MacOS system commands: - -```shell -Shell > bash sbin/start-cli.sh -h {host} -p {rpcPort} -u {user} -pw {password} -e {sql for iotdb} -``` - -The Windows system commands: - -```shell -# Before version V2.0.4.x -Shell > sbin\start-cli.bat -h {host} -p {rpcPort} -u {user} -pw {password} -e {sql for iotdb} - -# V2.0.4.x and later versions -Shell > sbin\windows\start-cli.bat -h {host} -p {rpcPort} -u {user} -pw {password} -e {sql for iotdb} -``` - -In the Windows environment, the SQL statement of the -e parameter needs to use ` `` ` to replace `" "` - -In order to better explain the use of -e parameter, take following as an example(On linux system). - -Suppose you want to create a database root.demo to a newly launched IoTDB, create a timeseries root.demo.s1 and insert three data points into it. With -e parameter, you could write a shell like this: - -```shell -# !/bin/bash - -host=127.0.0.1 -rpcPort=6667 -user=root -pass=root - -bash ./sbin/start-cli.sh -h ${host} -p ${rpcPort} -u ${user} -pw ${pass} -e "create database root.demo" -bash ./sbin/start-cli.sh -h ${host} -p ${rpcPort} -u ${user} -pw ${pass} -e "create timeseries root.demo.s1 WITH DATATYPE=INT32, ENCODING=RLE" -bash ./sbin/start-cli.sh -h ${host} -p ${rpcPort} -u ${user} -pw ${pass} -e "insert into root.demo(timestamp,s1) values(1,10)" -bash ./sbin/start-cli.sh -h ${host} -p ${rpcPort} -u ${user} -pw ${pass} -e "insert into root.demo(timestamp,s1) values(2,11)" -bash ./sbin/start-cli.sh -h ${host} -p ${rpcPort} -u ${user} -pw ${pass} -e "insert into root.demo(timestamp,s1) values(3,12)" -bash ./sbin/start-cli.sh -h ${host} -p ${rpcPort} -u ${user} -pw ${pass} -e "select s1 from root.demo" -``` - -The results are shown in the figure, which are consistent with the Cli and jdbc operations. - -```shell - Shell > bash ./shell.sh -+-----------------------------+------------+ -| Time|root.demo.s1| -+-----------------------------+------------+ -|1970-01-01T08:00:00.001+08:00| 10| -|1970-01-01T08:00:00.002+08:00| 11| -|1970-01-01T08:00:00.003+08:00| 12| -+-----------------------------+------------+ -Total line number = 3 -It costs 0.267s -``` - -It should be noted that the use of the -e parameter in shell scripts requires attention to the escaping of special characters. +--> \ No newline at end of file diff --git a/src/UserGuide/latest/Tools-System/CLI_apache.md b/src/UserGuide/latest/Tools-System/CLI_apache.md new file mode 100644 index 000000000..665af2052 --- /dev/null +++ b/src/UserGuide/latest/Tools-System/CLI_apache.md @@ -0,0 +1,307 @@ + + +# Command Line Interface (CLI) + + +IoTDB provides Cli/shell tools for users to interact with IoTDB server in command lines. This document shows how Cli/shell tool works and the meaning of its parameters. + +> Note: In this document, \$IOTDB\_HOME represents the path of the IoTDB installation directory. + +## 1. Installation + +If you use the source code version of IoTDB, then under the root path of IoTDB, execute: + +```shell +> mvn clean package -pl iotdb-client/cli -am -DskipTests -P get-jar-with-dependencies +``` + +After build, the IoTDB Cli will be in the folder "cli/target/iotdb-cli-{project.version}". + +If you download the binary version, then the Cli can be used directly in sbin folder. + +## 2. Running + +### 2.1 Running Cli + +After installation, there is a default user in IoTDB: `root`, and the +default password is `root`. Users can use this username to try IoTDB Cli/Shell tool. The cli startup script is the `start-cli` file under the \$IOTDB\_HOME/bin folder. When starting the script, you need to specify the IP and PORT. (Make sure the IoTDB cluster is running properly when you use Cli/Shell tool to connect to it.) + +Here is an example where the cluster is started locally and the user has not changed the running port. The default rpc port is +6667
+If you need to connect to the remote DataNode or changes +the rpc port number of the DataNode running, set the specific IP and RPC PORT at -h and -p.
+You also can set your own environment variable at the front of the start script + +The Linux and MacOS system startup commands are as follows: + +```shell +Shell > bash sbin/start-cli.sh -h 127.0.0.1 -p 6667 -u root -pw root +``` + +The Windows system startup commands are as follows: + +```shell +# Before version V2.0.4.x +Shell > sbin\start-cli.bat -h 127.0.0.1 -p 6667 -u root -pw root + +# V2.0.4.x and later versions +Shell > sbin\windows\start-cli.bat -h 127.0.0.1 -p 6667 -u root -pw root +``` + +After operating these commands, the cli can be started successfully. The successful status will be as follows: + +``` + _____ _________ ______ ______ +|_ _| | _ _ ||_ _ `.|_ _ \ + | | .--.|_/ | | \_| | | `. \ | |_) | + | | / .'`\ \ | | | | | | | __'. + _| |_| \__. | _| |_ _| |_.' /_| |__) | +|_____|'.__.' |_____| |______.'|_______/ version + + +Successfully login at 127.0.0.1:6667 +IoTDB> +``` + +Enter ```quit``` or `exit` can exit Cli. + +### 2.2 Cli Parameters + +| Parameter name | Parameter type | Required | Description | Example | +| :--------------------------- | :------------------------- | :------- | :----------------------------------------------------------- | :------------------ | +| -disableISO8601 | No parameters | No | If this parameter is set, IoTDB will print the timestamp in digital form | -disableISO8601 | +| -h <`host`> | string, no quotation marks | Yes | The IP address of the IoTDB server | -h 10.129.187.21 | +| -help | No parameters | No | Print help information for IoTDB | -help | +| -p <`rpcPort`> | int | Yes | The rpc port number of the IoTDB server. IoTDB runs on rpc port 6667 by default | -p 6667 | +| -pw <`password`> | string, no quotation marks | No | The password used for IoTDB to connect to the server. If no password is entered, IoTDB will ask for password in Cli command | -pw root | +| -u <`username`> | string, no quotation marks | Yes | User name used for IoTDB to connect the server | -u root | +| -maxPRC <`maxPrintRowCount`> | int | No | Set the maximum number of rows that IoTDB returns | -maxPRC 10 | +| -e <`execute`> | string | No | manipulate IoTDB in batches without entering cli input mode | -e "show databases" | +| -c | empty | No | If the server enables `rpc_thrift_compression_enable=true`, then cli must use `-c` | -c | + +Following is a cli command which connects the host with IP +10.129.187.21, rpc port 6667, username "root", password "root", and prints the timestamp in digital form. The maximum number of lines displayed on the IoTDB command line is 10. + +The Linux and MacOS system startup commands are as follows: + +```shell +Shell > bash sbin/start-cli.sh -h 10.129.187.21 -p 6667 -u root -pw root -disableISO8601 -maxPRC 10 +``` + +The Windows system startup commands are as follows: + +```shell +# Before version V2.0.4.x +Shell > sbin\start-cli.bat -h 10.129.187.21 -p 6667 -u root -pw root -disableISO8601 -maxPRC 10 + +# # V2.0.4.x and later versions +Shell > sbin\windows\start-cli.bat -h 10.129.187.21 -p 6667 -u root -pw root -disableISO8601 -maxPRC 10 +``` + +### 2.3 CLI Special Command + +Special commands of Cli are below. + +| Command | Description / Example | +| :-------------------------- | :------------------------------------------------------ | +| `set time_display_type=xxx` | eg. long, default, ISO8601, yyyy-MM-dd HH:mm:ss | +| `show time_display_type` | show time display type | +| `set time_zone=xxx` | eg. +08:00, Asia/Shanghai | +| `show time_zone` | show cli time zone | +| `set fetch_size=xxx` | set fetch size when querying data from server | +| `show fetch_size` | show fetch size | +| `set max_display_num=xxx` | set max lines for cli to output, -1 equals to unlimited | +| `help` | Get hints for CLI special commands | +| `exit/quit` | Exit CLI | + +### 2.4 Note on using the CLI with OpenID Connect Auth enabled on Server side + +Openid connect (oidc) uses keycloack as the authority authentication service of oidc service + + +#### configuration + +The configuration is located in iotdb-system.properties , set the author_provider_class is org.apache.iotdb.commons.auth.authorizer.OpenIdAuthorizer Openid service is enabled, and the default value is org.apache.iotdb.db.auth.authorizer.LocalFileAuthorizer Indicates that the openid service is not enabled. + +``` +authorizer_provider_class=org.apache.iotdb.commons.auth.authorizer.OpenIdAuthorizer +``` + +If the openid service is turned on, openid_URL is required,openID_url value is http://ip:port/realms/{realmsName} + +``` +openID_url=http://127.0.0.1:8080/realms/iotdb/ +``` + +#### keycloack configuration + +1、Download the keycloack file (This tutorial is version 21.1.0) and start keycloack in keycloack/bin + +```shell +Shell >cd bin +Shell >./kc.sh start-dev +``` + +2、use url(https://ip:port) login keycloack, the first login needs to create a user +![avatar](/img/UserGuide/CLI/Command-Line-Interface/login_keycloak.png?raw=true) + +3、Click administration console +![avatar](/img/UserGuide/CLI/Command-Line-Interface/AdministrationConsole.png?raw=true) + +4、In the master menu on the left, click Create realm and enter Realm name to create a new realm +![avatar](/img/UserGuide/CLI/Command-Line-Interface/add_Realm_1.jpg?raw=true) + +![avatar](/img/UserGuide/CLI/Command-Line-Interface/add_Realm_2.jpg?raw=true) + + +5、Click the menu clients on the left to create clients + +![avatar](/img/UserGuide/CLI/Command-Line-Interface/client.jpg?raw=true) + +6、Click user on the left menu to create user + +![avatar](/img/UserGuide/CLI/Command-Line-Interface/user.jpg?raw=true) + +7、Click the newly created user ID, click the credentials navigation, enter the password and close the temporary option. The configuration of keycloud is completed + +![avatar](/img/UserGuide/CLI/Command-Line-Interface/pwd.jpg?raw=true) + +8、To create a role, click Roles on the left menu and then click the Create Role button to add a role + +![avatar](/img/UserGuide/CLI/Command-Line-Interface/add_role1.jpg?raw=true) + +9、 Enter `iotdb_admin` in the Role Name and click the save button. Tip: `iotdb_admin` here cannot be any other name, otherwise even after successful login, you will not have permission to use iotdb's query, insert, create database, add users, roles and other functions + +![avatar](/img/UserGuide/CLI/Command-Line-Interface/add_role2.jpg?raw=true) + +10、Click on the User menu on the left and then click on the user in the user list to add the `iotdb_admin` role we just created for that user + +![avatar](/img/UserGuide/CLI/Command-Line-Interface/add_role3.jpg?raw=true) + +11、 Select Role Mappings, select the `iotdb_admin` role in Assign Role + +![avatar](/img/UserGuide/CLI/Command-Line-Interface/add_role4.jpg?raw=true) + +![avatar](/img/UserGuide/CLI/Command-Line-Interface/add_role5.jpg?raw=true) + + +Tip: If the user role is adjusted, you need to regenerate the token and log in to iotdb again to take effect + +The above steps provide a way for keycloak to log into iotdb. For more ways, please refer to keycloak configuration + +If OIDC is enabled on server side then no username / passwort is needed but a valid Access Token from the OIDC Provider. +So as username you use the token and the password has to be empty, e.g. + +```shell +Shell > bash sbin/start-cli.sh -h 10.129.187.21 -p 6667 -u {my-access-token} -pw "" +``` + +Among them, you need to replace {my access token} (note, including {}) with your token, that is, the value corresponding to access_token. The password is empty and needs to be confirmed again. + +![avatar](/img/UserGuide/CLI/Command-Line-Interface/iotdbpw.jpeg?raw=true) + + +How to get the token is dependent on your OpenID Connect setup and not covered here. +In the simplest case you can get this via the command line with the `passwort-grant`. +For example, if you use keycloack as OIDC and you have a realm with a client `iotdb` defined as public you could use +the following `curl` command to fetch a token (replace all `{}` with appropriate values). + +```shell +curl -X POST "https://{your-keycloack-server}/realms/{your-realm}/protocol/openid-connect/token" \ + -H "Content-Type: application/x-www-form-urlencoded" \ + -d "username={username}" \ + -d "password={password}" \ + -d 'grant_type=password' \ + -d "client_id=iotdb-client" +``` + +The response looks something like + +```json +{"access_token":"eyJhbGciOiJSUzI1NiIsInR5cCIgOiAiSldUIiwia2lkIiA6ICJxMS1XbTBvelE1TzBtUUg4LVNKYXAyWmNONE1tdWNXd25RV0tZeFpKNG93In0.eyJleHAiOjE1OTAzOTgwNzEsImlhdCI6MTU5MDM5Nzc3MSwianRpIjoiNjA0ZmYxMDctN2NiNy00NTRmLWIwYmQtY2M2ZDQwMjFiNGU4IiwiaXNzIjoiaHR0cDovL2F1dGguZGVtby5wcmFnbWF0aWNpbmR1c3RyaWVzLmRlL2F1dGgvcmVhbG1zL0lvVERCIiwiYXVkIjoiYWNjb3VudCIsInN1YiI6ImJhMzJlNDcxLWM3NzItNGIzMy04ZGE2LTZmZThhY2RhMDA3MyIsInR5cCI6IkJlYXJlciIsImF6cCI6ImlvdGRiIiwic2Vzc2lvbl9zdGF0ZSI6IjA2MGQyODYyLTE0ZWQtNDJmZS1iYWY3LThkMWY3ODQ2NTdmMSIsImFjciI6IjEiLCJhbGxvd2VkLW9yaWdpbnMiOlsibG9jYWxob3N0OjgwODAiXSwicmVhbG1fYWNjZXNzIjp7InJvbGVzIjpbIm9mZmxpbmVfYWNjZXNzIiwidW1hX2F1dGhvcml6YXRpb24iLCJpb3RkYl9hZG1pbiJdfSwicmVzb3VyY2VfYWNjZXNzIjp7ImFjY291bnQiOnsicm9sZXMiOlsibWFuYWdlLWFjY291bnQiLCJtYW5hZ2UtYWNjb3VudC1saW5rcyIsInZpZXctcHJvZmlsZSJdfX0sInNjb3BlIjoiZW1haWwgcHJvZmlsZSIsImVtYWlsX3ZlcmlmaWVkIjp0cnVlLCJwcmVmZXJyZWRfdXNlcm5hbWUiOiJ1c2VyIn0.nwbrJkWdCNjzFrTDwKNuV5h9dDMg5ytRKGOXmFIajpfsbOutJytjWTCB2WpA8E1YI3KM6gU6Jx7cd7u0oPo5syHhfCz119n_wBiDnyTZkFOAPsx0M2z20kvBLN9k36_VfuCMFUeddJjO31MeLTmxB0UKg2VkxdczmzMH3pnalhxqpnWWk3GnrRrhAf2sZog0foH4Ae3Ks0lYtYzaWK_Yo7E4Px42-gJpohy3JevOC44aJ4auzJR1RBj9LUbgcRinkBy0JLi6XXiYznSC2V485CSBHW3sseXn7pSXQADhnmGQrLfFGO5ZljmPO18eFJaimdjvgSChsrlSEmTDDsoo5Q","expires_in":300,"refresh_expires_in":1800,"refresh_token":"eyJhbGciOiJIUzI1NiIsInR5cCIgOiAiSldUIiwia2lkIiA6ICJhMzZlMGU0NC02MWNmLTQ5NmMtOGRlZi03NTkwNjQ5MzQzMjEifQ.eyJleHAiOjE1OTAzOTk1NzEsImlhdCI6MTU5MDM5Nzc3MSwianRpIjoiNmMxNTBiY2EtYmE5NC00NTgxLWEwODEtYjI2YzhhMmI5YmZmIiwiaXNzIjoiaHR0cDovL2F1dGguZGVtby5wcmFnbWF0aWNpbmR1c3RyaWVzLmRlL2F1dGgvcmVhbG1zL0lvVERCIiwiYXVkIjoiaHR0cDovL2F1dGguZGVtby5wcmFnbWF0aWNpbmR1c3RyaWVzLmRlL2F1dGgvcmVhbG1zL0lvVERCIiwic3ViIjoiYmEzMmU0NzEtYzc3Mi00YjMzLThkYTYtNmZlOGFjZGEwMDczIiwidHlwIjoiUmVmcmVzaCIsImF6cCI6ImlvdGRiIiwic2Vzc2lvbl9zdGF0ZSI6IjA2MGQyODYyLTE0ZWQtNDJmZS1iYWY3LThkMWY3ODQ2NTdmMSIsInNjb3BlIjoiZW1haWwgcHJvZmlsZSJ9.ayNpXdNX28qahodX1zowrMGiUCw2AodlHBQFqr8Ui7c","token_type":"bearer","not-before-policy":0,"session_state":"060d2862-14ed-42fe-baf7-8d1f784657f1","scope":"email profile"} +``` + +The interesting part here is the access token with the key `access_token`. +This has to be passed as username (with parameter `-u`) and empty password to the CLI. + +### 2.5 Batch Operation of Cli + +-e parameter is designed for the Cli/shell tool in the situation where you would like to manipulate IoTDB in batches through scripts. By using the -e parameter, you can operate IoTDB without entering the cli's input mode. + +In order to avoid confusion between statements and other parameters, the current version only supports the -e parameter as the last parameter. + +The usage of -e parameter for Cli/shell is as follows: + +The Linux and MacOS system commands: + +```shell +Shell > bash sbin/start-cli.sh -h {host} -p {rpcPort} -u {user} -pw {password} -e {sql for iotdb} +``` + +The Windows system commands: + +```shell +# Before version V2.0.4.x +Shell > sbin\start-cli.bat -h {host} -p {rpcPort} -u {user} -pw {password} -e {sql for iotdb} + +# V2.0.4.x and later versions +Shell > sbin\windows\start-cli.bat -h {host} -p {rpcPort} -u {user} -pw {password} -e {sql for iotdb} +``` + +In the Windows environment, the SQL statement of the -e parameter needs to use ` `` ` to replace `" "` + +In order to better explain the use of -e parameter, take following as an example(On linux system). + +Suppose you want to create a database root.demo to a newly launched IoTDB, create a timeseries root.demo.s1 and insert three data points into it. With -e parameter, you could write a shell like this: + +```shell +# !/bin/bash + +host=127.0.0.1 +rpcPort=6667 +user=root +pass=root + +bash ./sbin/start-cli.sh -h ${host} -p ${rpcPort} -u ${user} -pw ${pass} -e "create database root.demo" +bash ./sbin/start-cli.sh -h ${host} -p ${rpcPort} -u ${user} -pw ${pass} -e "create timeseries root.demo.s1 WITH DATATYPE=INT32, ENCODING=RLE" +bash ./sbin/start-cli.sh -h ${host} -p ${rpcPort} -u ${user} -pw ${pass} -e "insert into root.demo(timestamp,s1) values(1,10)" +bash ./sbin/start-cli.sh -h ${host} -p ${rpcPort} -u ${user} -pw ${pass} -e "insert into root.demo(timestamp,s1) values(2,11)" +bash ./sbin/start-cli.sh -h ${host} -p ${rpcPort} -u ${user} -pw ${pass} -e "insert into root.demo(timestamp,s1) values(3,12)" +bash ./sbin/start-cli.sh -h ${host} -p ${rpcPort} -u ${user} -pw ${pass} -e "select s1 from root.demo" +``` + +The results are shown in the figure, which are consistent with the Cli and jdbc operations. + +```shell + Shell > bash ./shell.sh ++-----------------------------+------------+ +| Time|root.demo.s1| ++-----------------------------+------------+ +|1970-01-01T08:00:00.001+08:00| 10| +|1970-01-01T08:00:00.002+08:00| 11| +|1970-01-01T08:00:00.003+08:00| 12| ++-----------------------------+------------+ +Total line number = 3 +It costs 0.267s +``` + +It should be noted that the use of the -e parameter in shell scripts requires attention to the escaping of special characters. diff --git a/src/UserGuide/latest/Tools-System/CLI_timecho.md b/src/UserGuide/latest/Tools-System/CLI_timecho.md new file mode 100644 index 000000000..a756abe34 --- /dev/null +++ b/src/UserGuide/latest/Tools-System/CLI_timecho.md @@ -0,0 +1,293 @@ + + +# Command Line Interface (CLI) + + +IoTDB provides Cli/shell tools for users to interact with IoTDB server in command lines. This document shows how Cli/shell tool works and the meaning of its parameters. + +> Note: In this document, \$IOTDB\_HOME represents the path of the IoTDB installation directory. + +## 1. Running Cli + +After installation, there is a default user in IoTDB: `root`, and the +default password is `root`. Users can use this username to try IoTDB Cli/Shell tool. The cli startup script is the `start-cli` file under the \$IOTDB\_HOME/bin folder. When starting the script, you need to specify the IP and PORT. (Make sure the IoTDB cluster is running properly when you use Cli/Shell tool to connect to it.) + +Here is an example where the cluster is started locally and the user has not changed the running port. The default rpc port is +6667
+If you need to connect to the remote DataNode or changes +the rpc port number of the DataNode running, set the specific IP and RPC PORT at -h and -p.
+You also can set your own environment variable at the front of the start script + +The Linux and MacOS system startup commands are as follows: + +```shell +Shell > bash sbin/start-cli.sh -h 127.0.0.1 -p 6667 -u root -pw root +``` + +The Windows system startup commands are as follows: + +```shell +# Before version V2.0.4.x +Shell > sbin\start-cli.bat -h 127.0.0.1 -p 6667 -u root -pw root + +# V2.0.4.x and later versions +Shell > sbin\windows\start-cli.bat -h 127.0.0.1 -p 6667 -u root -pw root +``` + +After operating these commands, the cli can be started successfully. The successful status will be as follows: + +``` + _____ _________ ______ ______ +|_ _| | _ _ ||_ _ `.|_ _ \ + | | .--.|_/ | | \_| | | `. \ | |_) | + | | / .'`\ \ | | | | | | | __'. + _| |_| \__. | _| |_ _| |_.' /_| |__) | +|_____|'.__.' |_____| |______.'|_______/ version + + +Successfully login at 127.0.0.1:6667 +IoTDB> +``` + +Enter ```quit``` or `exit` can exit Cli. + +## 2. Cli Parameters + +| Parameter name | Parameter type | Required | Description | Example | +| :--------------------------- | :------------------------- | :------- | :----------------------------------------------------------- | :------------------ | +| -disableISO8601 | No parameters | No | If this parameter is set, IoTDB will print the timestamp in digital form | -disableISO8601 | +| -h <`host`> | string, no quotation marks | Yes | The IP address of the IoTDB server | -h 10.129.187.21 | +| -help | No parameters | No | Print help information for IoTDB | -help | +| -p <`rpcPort`> | int | Yes | The rpc port number of the IoTDB server. IoTDB runs on rpc port 6667 by default | -p 6667 | +| -pw <`password`> | string, no quotation marks | No | The password used for IoTDB to connect to the server. If no password is entered, IoTDB will ask for password in Cli command | -pw root | +| -u <`username`> | string, no quotation marks | Yes | User name used for IoTDB to connect the server | -u root | +| -maxPRC <`maxPrintRowCount`> | int | No | Set the maximum number of rows that IoTDB returns | -maxPRC 10 | +| -e <`execute`> | string | No | manipulate IoTDB in batches without entering cli input mode | -e "show databases" | +| -c | empty | No | If the server enables `rpc_thrift_compression_enable=true`, then cli must use `-c` | -c | + +Following is a cli command which connects the host with IP +10.129.187.21, rpc port 6667, username "root", password "root", and prints the timestamp in digital form. The maximum number of lines displayed on the IoTDB command line is 10. + +The Linux and MacOS system startup commands are as follows: + +```shell +Shell > bash sbin/start-cli.sh -h 10.129.187.21 -p 6667 -u root -pw root -disableISO8601 -maxPRC 10 +``` + +The Windows system startup commands are as follows: + +```shell +# Before version V2.0.4.x +Shell > sbin\start-cli.bat -h 10.129.187.21 -p 6667 -u root -pw root -disableISO8601 -maxPRC 10 + +# # V2.0.4.x and later versions +Shell > sbin\windows\start-cli.bat -h 10.129.187.21 -p 6667 -u root -pw root -disableISO8601 -maxPRC 10 +``` + +## 3. CLI Special Command + +Special commands of Cli are below. + +| Command | Description / Example | +| :-------------------------- | :------------------------------------------------------ | +| `set time_display_type=xxx` | eg. long, default, ISO8601, yyyy-MM-dd HH:mm:ss | +| `show time_display_type` | show time display type | +| `set time_zone=xxx` | eg. +08:00, Asia/Shanghai | +| `show time_zone` | show cli time zone | +| `set fetch_size=xxx` | set fetch size when querying data from server | +| `show fetch_size` | show fetch size | +| `set max_display_num=xxx` | set max lines for cli to output, -1 equals to unlimited | +| `help` | Get hints for CLI special commands | +| `exit/quit` | Exit CLI | + +## 4. Note on using the CLI with OpenID Connect Auth enabled on Server side + +Openid connect (oidc) uses keycloack as the authority authentication service of oidc service + + +#### configuration + +The configuration is located in iotdb-system.properties , set the author_provider_class is org.apache.iotdb.commons.auth.authorizer.OpenIdAuthorizer Openid service is enabled, and the default value is org.apache.iotdb.db.auth.authorizer.LocalFileAuthorizer Indicates that the openid service is not enabled. + +``` +authorizer_provider_class=org.apache.iotdb.commons.auth.authorizer.OpenIdAuthorizer +``` + +If the openid service is turned on, openid_URL is required,openID_url value is http://ip:port/realms/{realmsName} + +``` +openID_url=http://127.0.0.1:8080/realms/iotdb/ +``` + +#### keycloack configuration + +1、Download the keycloack file (This tutorial is version 21.1.0) and start keycloack in keycloack/bin + +```shell +Shell >cd bin +Shell >./kc.sh start-dev +``` + +2、use url(https://ip:port) login keycloack, the first login needs to create a user +![avatar](/img/UserGuide/CLI/Command-Line-Interface/login_keycloak.png?raw=true) + +3、Click administration console +![avatar](/img/UserGuide/CLI/Command-Line-Interface/AdministrationConsole.png?raw=true) + +4、In the master menu on the left, click Create realm and enter Realm name to create a new realm +![avatar](/img/UserGuide/CLI/Command-Line-Interface/add_Realm_1.jpg?raw=true) + +![avatar](/img/UserGuide/CLI/Command-Line-Interface/add_Realm_2.jpg?raw=true) + + +5、Click the menu clients on the left to create clients + +![avatar](/img/UserGuide/CLI/Command-Line-Interface/client.jpg?raw=true) + +6、Click user on the left menu to create user + +![avatar](/img/UserGuide/CLI/Command-Line-Interface/user.jpg?raw=true) + +7、Click the newly created user ID, click the credentials navigation, enter the password and close the temporary option. The configuration of keycloud is completed + +![avatar](/img/UserGuide/CLI/Command-Line-Interface/pwd.jpg?raw=true) + +8、To create a role, click Roles on the left menu and then click the Create Role button to add a role + +![avatar](/img/UserGuide/CLI/Command-Line-Interface/add_role1.jpg?raw=true) + +9、 Enter `iotdb_admin` in the Role Name and click the save button. Tip: `iotdb_admin` here cannot be any other name, otherwise even after successful login, you will not have permission to use iotdb's query, insert, create database, add users, roles and other functions + +![avatar](/img/UserGuide/CLI/Command-Line-Interface/add_role2.jpg?raw=true) + +10、Click on the User menu on the left and then click on the user in the user list to add the `iotdb_admin` role we just created for that user + +![avatar](/img/UserGuide/CLI/Command-Line-Interface/add_role3.jpg?raw=true) + +11、 Select Role Mappings, select the `iotdb_admin` role in Assign Role + +![avatar](/img/UserGuide/CLI/Command-Line-Interface/add_role4.jpg?raw=true) + +![avatar](/img/UserGuide/CLI/Command-Line-Interface/add_role5.jpg?raw=true) + + +Tip: If the user role is adjusted, you need to regenerate the token and log in to iotdb again to take effect + +The above steps provide a way for keycloak to log into iotdb. For more ways, please refer to keycloak configuration + +If OIDC is enabled on server side then no username / passwort is needed but a valid Access Token from the OIDC Provider. +So as username you use the token and the password has to be empty, e.g. + +```shell +Shell > bash sbin/start-cli.sh -h 10.129.187.21 -p 6667 -u {my-access-token} -pw "" +``` + +Among them, you need to replace {my access token} (note, including {}) with your token, that is, the value corresponding to access_token. The password is empty and needs to be confirmed again. + +![avatar](/img/UserGuide/CLI/Command-Line-Interface/iotdbpw.jpeg?raw=true) + + +How to get the token is dependent on your OpenID Connect setup and not covered here. +In the simplest case you can get this via the command line with the `passwort-grant`. +For example, if you use keycloack as OIDC and you have a realm with a client `iotdb` defined as public you could use +the following `curl` command to fetch a token (replace all `{}` with appropriate values). + +```shell +curl -X POST "https://{your-keycloack-server}/realms/{your-realm}/protocol/openid-connect/token" \ + -H "Content-Type: application/x-www-form-urlencoded" \ + -d "username={username}" \ + -d "password={password}" \ + -d 'grant_type=password' \ + -d "client_id=iotdb-client" +``` + +The response looks something like + +```json +{"access_token":"eyJhbGciOiJSUzI1NiIsInR5cCIgOiAiSldUIiwia2lkIiA6ICJxMS1XbTBvelE1TzBtUUg4LVNKYXAyWmNONE1tdWNXd25RV0tZeFpKNG93In0.eyJleHAiOjE1OTAzOTgwNzEsImlhdCI6MTU5MDM5Nzc3MSwianRpIjoiNjA0ZmYxMDctN2NiNy00NTRmLWIwYmQtY2M2ZDQwMjFiNGU4IiwiaXNzIjoiaHR0cDovL2F1dGguZGVtby5wcmFnbWF0aWNpbmR1c3RyaWVzLmRlL2F1dGgvcmVhbG1zL0lvVERCIiwiYXVkIjoiYWNjb3VudCIsInN1YiI6ImJhMzJlNDcxLWM3NzItNGIzMy04ZGE2LTZmZThhY2RhMDA3MyIsInR5cCI6IkJlYXJlciIsImF6cCI6ImlvdGRiIiwic2Vzc2lvbl9zdGF0ZSI6IjA2MGQyODYyLTE0ZWQtNDJmZS1iYWY3LThkMWY3ODQ2NTdmMSIsImFjciI6IjEiLCJhbGxvd2VkLW9yaWdpbnMiOlsibG9jYWxob3N0OjgwODAiXSwicmVhbG1fYWNjZXNzIjp7InJvbGVzIjpbIm9mZmxpbmVfYWNjZXNzIiwidW1hX2F1dGhvcml6YXRpb24iLCJpb3RkYl9hZG1pbiJdfSwicmVzb3VyY2VfYWNjZXNzIjp7ImFjY291bnQiOnsicm9sZXMiOlsibWFuYWdlLWFjY291bnQiLCJtYW5hZ2UtYWNjb3VudC1saW5rcyIsInZpZXctcHJvZmlsZSJdfX0sInNjb3BlIjoiZW1haWwgcHJvZmlsZSIsImVtYWlsX3ZlcmlmaWVkIjp0cnVlLCJwcmVmZXJyZWRfdXNlcm5hbWUiOiJ1c2VyIn0.nwbrJkWdCNjzFrTDwKNuV5h9dDMg5ytRKGOXmFIajpfsbOutJytjWTCB2WpA8E1YI3KM6gU6Jx7cd7u0oPo5syHhfCz119n_wBiDnyTZkFOAPsx0M2z20kvBLN9k36_VfuCMFUeddJjO31MeLTmxB0UKg2VkxdczmzMH3pnalhxqpnWWk3GnrRrhAf2sZog0foH4Ae3Ks0lYtYzaWK_Yo7E4Px42-gJpohy3JevOC44aJ4auzJR1RBj9LUbgcRinkBy0JLi6XXiYznSC2V485CSBHW3sseXn7pSXQADhnmGQrLfFGO5ZljmPO18eFJaimdjvgSChsrlSEmTDDsoo5Q","expires_in":300,"refresh_expires_in":1800,"refresh_token":"eyJhbGciOiJIUzI1NiIsInR5cCIgOiAiSldUIiwia2lkIiA6ICJhMzZlMGU0NC02MWNmLTQ5NmMtOGRlZi03NTkwNjQ5MzQzMjEifQ.eyJleHAiOjE1OTAzOTk1NzEsImlhdCI6MTU5MDM5Nzc3MSwianRpIjoiNmMxNTBiY2EtYmE5NC00NTgxLWEwODEtYjI2YzhhMmI5YmZmIiwiaXNzIjoiaHR0cDovL2F1dGguZGVtby5wcmFnbWF0aWNpbmR1c3RyaWVzLmRlL2F1dGgvcmVhbG1zL0lvVERCIiwiYXVkIjoiaHR0cDovL2F1dGguZGVtby5wcmFnbWF0aWNpbmR1c3RyaWVzLmRlL2F1dGgvcmVhbG1zL0lvVERCIiwic3ViIjoiYmEzMmU0NzEtYzc3Mi00YjMzLThkYTYtNmZlOGFjZGEwMDczIiwidHlwIjoiUmVmcmVzaCIsImF6cCI6ImlvdGRiIiwic2Vzc2lvbl9zdGF0ZSI6IjA2MGQyODYyLTE0ZWQtNDJmZS1iYWY3LThkMWY3ODQ2NTdmMSIsInNjb3BlIjoiZW1haWwgcHJvZmlsZSJ9.ayNpXdNX28qahodX1zowrMGiUCw2AodlHBQFqr8Ui7c","token_type":"bearer","not-before-policy":0,"session_state":"060d2862-14ed-42fe-baf7-8d1f784657f1","scope":"email profile"} +``` + +The interesting part here is the access token with the key `access_token`. +This has to be passed as username (with parameter `-u`) and empty password to the CLI. + +## 5. Batch Operation of Cli + +-e parameter is designed for the Cli/shell tool in the situation where you would like to manipulate IoTDB in batches through scripts. By using the -e parameter, you can operate IoTDB without entering the cli's input mode. + +In order to avoid confusion between statements and other parameters, the current version only supports the -e parameter as the last parameter. + +The usage of -e parameter for Cli/shell is as follows: + +The Linux and MacOS system commands: + +```shell +Shell > bash sbin/start-cli.sh -h {host} -p {rpcPort} -u {user} -pw {password} -e {sql for iotdb} +``` + +The Windows system commands: + +```shell +# Before version V2.0.4.x +Shell > sbin\start-cli.bat -h {host} -p {rpcPort} -u {user} -pw {password} -e {sql for iotdb} + +# V2.0.4.x and later versions +Shell > sbin\windows\start-cli.bat -h {host} -p {rpcPort} -u {user} -pw {password} -e {sql for iotdb} +``` + +In the Windows environment, the SQL statement of the -e parameter needs to use ` `` ` to replace `" "` + +In order to better explain the use of -e parameter, take following as an example(On linux system). + +Suppose you want to create a database root.demo to a newly launched IoTDB, create a timeseries root.demo.s1 and insert three data points into it. With -e parameter, you could write a shell like this: + +```shell +# !/bin/bash + +host=127.0.0.1 +rpcPort=6667 +user=root +pass=root + +bash ./sbin/start-cli.sh -h ${host} -p ${rpcPort} -u ${user} -pw ${pass} -e "create database root.demo" +bash ./sbin/start-cli.sh -h ${host} -p ${rpcPort} -u ${user} -pw ${pass} -e "create timeseries root.demo.s1 WITH DATATYPE=INT32, ENCODING=RLE" +bash ./sbin/start-cli.sh -h ${host} -p ${rpcPort} -u ${user} -pw ${pass} -e "insert into root.demo(timestamp,s1) values(1,10)" +bash ./sbin/start-cli.sh -h ${host} -p ${rpcPort} -u ${user} -pw ${pass} -e "insert into root.demo(timestamp,s1) values(2,11)" +bash ./sbin/start-cli.sh -h ${host} -p ${rpcPort} -u ${user} -pw ${pass} -e "insert into root.demo(timestamp,s1) values(3,12)" +bash ./sbin/start-cli.sh -h ${host} -p ${rpcPort} -u ${user} -pw ${pass} -e "select s1 from root.demo" +``` + +The results are shown in the figure, which are consistent with the Cli and jdbc operations. + +```shell + Shell > bash ./shell.sh ++-----------------------------+------------+ +| Time|root.demo.s1| ++-----------------------------+------------+ +|1970-01-01T08:00:00.001+08:00| 10| +|1970-01-01T08:00:00.002+08:00| 11| +|1970-01-01T08:00:00.003+08:00| 12| ++-----------------------------+------------+ +Total line number = 3 +It costs 0.267s +``` + +It should be noted that the use of the -e parameter in shell scripts requires attention to the escaping of special characters. diff --git a/src/zh/UserGuide/Master/Tree/Tools-System/CLI.md b/src/zh/UserGuide/Master/Tree/Tools-System/CLI.md index 23d3470bc..03580fafb 100644 --- a/src/zh/UserGuide/Master/Tree/Tools-System/CLI.md +++ b/src/zh/UserGuide/Master/Tree/Tools-System/CLI.md @@ -1,3 +1,6 @@ +--- +redirectTo: CLI_apache.html +--- - -# 命令行工具 - -IOTDB 为用户提供 cli/Shell 工具用于启动客户端和服务端程序。下面介绍每个 cli/Shell 工具的运行方式和相关参数。 -> \$IOTDB\_HOME 表示 IoTDB 的安装目录所在路径。 - -## 1. 安装 -如果使用源码版，可以在 iotdb 的根目录下执行 - -```shell -> mvn clean package -pl cli -am -DskipTests -``` - -在生成完毕之后，IoTDB 的 Cli 工具位于文件夹"cli/target/iotdb-cli-{project.version}"中。 - -如果你下载的是二进制版，那么 Cli 可以在 sbin 文件夹下直接找到。 - -## 2. 运行 - -### 2.1 Cli 运行方式 -安装后的 IoTDB 中有一个默认用户：`root`，默认密码为`root`。用户可以使用该用户尝试运行 IoTDB 客户端以测试服务器是否正常启动。客户端启动脚本为$IOTDB_HOME/sbin 文件夹下的`start-cli`脚本。启动脚本时需要指定运行 IP 和 RPC PORT。以下为服务器在本机启动，且用户未更改运行端口号的示例，默认端口为 6667。若用户尝试连接远程服务器或更改了服务器运行的端口号，请在-h 和-p 项处使用服务器的 IP 和 RPC PORT。
-用户也可以在启动脚本的最前方设置自己的环境变量，如 JAVA_HOME 等。 - -Linux 系统与 MacOS 系统启动命令如下： - -```shell -Shell > bash sbin/start-cli.sh -h 127.0.0.1 -p 6667 -u root -pw root -``` -Windows 系统启动命令如下： - -```shell -# V2.0.4.x 版本之前 -Shell > sbin\start-cli.bat -h 127.0.0.1 -p 6667 -u root -pw root - -# V2.0.4.x 版本及之后 -Shell > sbin\windows\start-cli.bat -h 127.0.0.1 -p 6667 -u root -pw root -``` -回车后即可成功启动客户端。启动后出现如图提示即为启动成功。 - -``` - _____ _________ ______ ______ -|_ _| | _ _ ||_ _ `.|_ _ \ - | | .--.|_/ | | \_| | | `. \ | |_) | - | | / .'`\ \ | | | | | | | __'. - _| |_| \__. | _| |_ _| |_.' /_| |__) | -|_____|'.__.' |_____| |______.'|_______/ version - -Successfully login at 127.0.0.1:6667 -``` -输入`quit`或`exit`可退出 cli 结束本次会话，cli 输出`quit normally`表示退出成功。 - -### 2.2 Cli 运行参数 - -|参数名|参数类型|是否为必需参数| 说明| 例子 | -|:---|:---|:---|:---|:---| -|-disableISO8601 |没有参数 | 否 |如果设置了这个参数，IoTDB 将以数字的形式打印时间戳 (timestamp)。|-disableISO8601| -|-h <`host`> |string 类型，不需要引号|是|IoTDB 客户端连接 IoTDB 服务器的 IP 地址。|-h 10.129.187.21| -|-help|没有参数|否|打印 IoTDB 的帮助信息|-help| -|-p <`rpcPort`>|int 类型|是|IoTDB 连接服务器的端口号，IoTDB 默认运行在 6667 端口。|-p 6667| -|-pw <`password`>|string 类型，不需要引号|否|IoTDB 连接服务器所使用的密码。如果没有输入密码 IoTDB 会在 Cli 端提示输入密码。|-pw root| -|-u <`username`>|string 类型，不需要引号|是|IoTDB 连接服务器锁使用的用户名。|-u root| -|-maxPRC <`maxPrintRowCount`>|int 类型|否|设置 IoTDB 返回客户端命令行中所显示的最大行数。|-maxPRC 10| -|-e <`execute`> |string 类型|否|在不进入客户端输入模式的情况下，批量操作 IoTDB|-e "show databases"| -|-c | 空 | 否 | 如果服务器设置了 `rpc_thrift_compression_enable=true`, 则 CLI 必须使用 `-c` | -c | - -下面展示一条客户端命令，功能是连接 IP 为 10.129.187.21 的主机，端口为 6667 ，用户名为 root，密码为 root，以数字的形式打印时间戳，IoTDB 命令行显示的最大行数为 10。 - -Linux 系统与 MacOS 系统启动命令如下： - -```shell -Shell > bash sbin/start-cli.sh -h 10.129.187.21 -p 6667 -u root -pw root -disableISO8601 -maxPRC 10 -``` -Windows 系统启动命令如下： - -```shell -# V2.0.4.x 版本之前 -Shell > sbin\start-cli.bat -h 10.129.187.21 -p 6667 -u root -pw root -disableISO8601 -maxPRC 10 - -# V2.0.4.x 版本及之后 -Shell > sbin\windows\start-cli.bat -h 10.129.187.21 -p 6667 -u root -pw root -disableISO8601 -maxPRC 10 -``` - -### 2.3 CLI 特殊命令 -下面列举了一些CLI的特殊命令。 - -| 命令 | 描述 / 例子 | -|:---|:---| -| `set time_display_type=xxx` | 例如： long, default, ISO8601, yyyy-MM-dd HH:mm:ss | -| `show time_display_type` | 显示时间显示方式 | -| `set time_zone=xxx` | 例如： +08:00, Asia/Shanghai | -| `show time_zone` | 显示CLI的时区 | -| `set fetch_size=xxx` | 设置从服务器查询数据时的读取条数 | -| `show fetch_size` | 显示读取条数的大小 | -| `set max_display_num=xxx` | 设置 CLI 一次展示的最大数据条数， 设置为-1表示无限制 | -| `help` | 获取CLI特殊命令的提示 | -| `exit/quit` | 退出CLI | - -### 2.4 使用 OpenID 作为用户名认证登录 - -OpenID Connect (OIDC) 使用 keycloack 作为 OIDC 服务权限认证服务。 - -#### 配置 -配置位于 iotdb-system.properties，设定 authorizer_provider_class 为 org.apache.iotdb.commons.auth.authorizer.OpenIdAuthorizer 则开启了 openID 服务，默认情况下值为 org.apache.iotdb.commons.auth.authorizer.LocalFileAuthorizer 表示没有开启 openID 服务。 - -``` -authorizer_provider_class=org.apache.iotdb.commons.auth.authorizer.OpenIdAuthorizer -``` -如果开启了 openID 服务则 openID_url 为必填项，openID_url 值为 http://ip:port/realms/{realmsName} - -``` -openID_url=http://127.0.0.1:8080/realms/iotdb/ -``` -####keycloack 配置 - -1、下载 keycloack 程序（此教程为21.1.0版本），在 keycloack/bin 中启动 keycloack - -```shell -Shell > cd bin -Shell > ./kc.sh start-dev -``` -2、使用 https://ip:port 登陆 keycloack, 首次登陆需要创建用户 - -![avatar](/img/UserGuide/CLI/Command-Line-Interface/login_keycloak.png?raw=true) - -3、点击 Administration Console 进入管理端 - -![avatar](/img/UserGuide/CLI/Command-Line-Interface/AdministrationConsole.png?raw=true) - -4、在左侧的 Master 菜单点击 Create Realm, 输入 Realm Name 创建一个新的 Realm - -![avatar](/img/UserGuide/CLI/Command-Line-Interface/add_Realm_1.jpg?raw=true) - -![avatar](/img/UserGuide/CLI/Command-Line-Interface/add_Realm_2.jpg?raw=true) - -5、点击左侧菜单 Clients，创建 client - -![avatar](/img/UserGuide/CLI/Command-Line-Interface/client.jpg?raw=true) - -6、点击左侧菜单 User，创建 user - -![avatar](/img/UserGuide/CLI/Command-Line-Interface/user.jpg?raw=true) - -7、点击新创建的用户 id，点击 Credentials 导航输入密码和关闭 Temporary 选项，至此 keyclork 配置完成 - -![avatar](/img/UserGuide/CLI/Command-Line-Interface/pwd.jpg?raw=true) - -8、创建角色，点击左侧菜单的 Roles然后点击Create Role 按钮添加角色 - -![avatar](/img/UserGuide/CLI/Command-Line-Interface/add_role1.jpg?raw=true) - -9、在Role Name 中输入`iotdb_admin`，点击save 按钮。提示：这里的`iotdb_admin`不能为其他名称否则即使登陆成功后也将无权限使用iotdb的查询、插入、创建 database、添加用户、角色等功能 - -![avatar](/img/UserGuide/CLI/Command-Line-Interface/add_role2.jpg?raw=true) - -10、点击左侧的User 菜单然后点击用户列表中的用户为该用户添加我们刚创建的`iotdb_admin`角色 - -![avatar](/img/UserGuide/CLI/Command-Line-Interface/add_role3.jpg?raw=true) - -11、选择Role Mappings ，在Assign role选择`iotdb_admin`增加角色 - -![avatar](/img/UserGuide/CLI/Command-Line-Interface/add_role4.jpg?raw=true) - -![avatar](/img/UserGuide/CLI/Command-Line-Interface/add_role5.jpg?raw=true) - -提示：如果用户角色有调整需要重新生成token并且重新登陆iotdb才会生效 - -以上步骤提供了一种 keycloak 登陆 iotdb 方式，更多方式请参考 keycloak 配置 - -若对应的 IoTDB 服务器开启了使用 OpenID Connect (OIDC) 作为权限认证服务，那么就不再需要使用用户名密码进行登录。 -替而代之的是使用 Token，以及空密码。 -此时，登录命令如下： - -```shell -Shell > bash sbin/start-cli.sh -h 10.129.187.21 -p 6667 -u {my-access-token} -pw "" -``` - -其中，需要将{my-access-token} （注意，包括{}）替换成你的 token，即 access_token 对应的值。密码为空需要再次确认。 - -![avatar](/img/UserGuide/CLI/Command-Line-Interface/iotdbpw.jpeg?raw=true) - -如何获取 token 取决于你的 OIDC 设置。 最简单的一种情况是使用`password-grant`。例如，假设你在用 keycloack 作为你的 OIDC 服务， -并且你在 keycloack 中有一个被定义成 public 的`iotdb`客户的 realm，那么你可以使用如下`curl`命令获得 token。 -（注意例子中的{}和里面的内容需要替换成具体的服务器地址和 realm 名字）： -```shell -curl -X POST "http://{your-keycloack-server}/realms/{your-realm}/protocol/openid-connect/token" \ -H "Content-Type: application/x-www-form-urlencoded" \ - -d "username={username}" \ - -d "password={password}" \ - -d 'grant_type=password' \ - -d "client_id=iotdb-client" -``` - -示例结果如下： - -```json -{"access_token":"eyJhbGciOiJSUzI1NiIsInR5cCIgOiAiSldUIiwia2lkIiA6ICJxMS1XbTBvelE1TzBtUUg4LVNKYXAyWmNONE1tdWNXd25RV0tZeFpKNG93In0.eyJleHAiOjE1OTAzOTgwNzEsImlhdCI6MTU5MDM5Nzc3MSwianRpIjoiNjA0ZmYxMDctN2NiNy00NTRmLWIwYmQtY2M2ZDQwMjFiNGU4IiwiaXNzIjoiaHR0cDovL2F1dGguZGVtby5wcmFnbWF0aWNpbmR1c3RyaWVzLmRlL2F1dGgvcmVhbG1zL0lvVERCIiwiYXVkIjoiYWNjb3VudCIsInN1YiI6ImJhMzJlNDcxLWM3NzItNGIzMy04ZGE2LTZmZThhY2RhMDA3MyIsInR5cCI6IkJlYXJlciIsImF6cCI6ImlvdGRiIiwic2Vzc2lvbl9zdGF0ZSI6IjA2MGQyODYyLTE0ZWQtNDJmZS1iYWY3LThkMWY3ODQ2NTdmMSIsImFjciI6IjEiLCJhbGxvd2VkLW9yaWdpbnMiOlsibG9jYWxob3N0OjgwODAiXSwicmVhbG1fYWNjZXNzIjp7InJvbGVzIjpbIm9mZmxpbmVfYWNjZXNzIiwidW1hX2F1dGhvcml6YXRpb24iLCJpb3RkYl9hZG1pbiJdfSwicmVzb3VyY2VfYWNjZXNzIjp7ImFjY291bnQiOnsicm9sZXMiOlsibWFuYWdlLWFjY291bnQiLCJtYW5hZ2UtYWNjb3VudC1saW5rcyIsInZpZXctcHJvZmlsZSJdfX0sInNjb3BlIjoiZW1haWwgcHJvZmlsZSIsImVtYWlsX3ZlcmlmaWVkIjp0cnVlLCJwcmVmZXJyZWRfdXNlcm5hbWUiOiJ1c2VyIn0.nwbrJkWdCNjzFrTDwKNuV5h9dDMg5ytRKGOXmFIajpfsbOutJytjWTCB2WpA8E1YI3KM6gU6Jx7cd7u0oPo5syHhfCz119n_wBiDnyTZkFOAPsx0M2z20kvBLN9k36_VfuCMFUeddJjO31MeLTmxB0UKg2VkxdczmzMH3pnalhxqpnWWk3GnrRrhAf2sZog0foH4Ae3Ks0lYtYzaWK_Yo7E4Px42-gJpohy3JevOC44aJ4auzJR1RBj9LUbgcRinkBy0JLi6XXiYznSC2V485CSBHW3sseXn7pSXQADhnmGQrLfFGO5ZljmPO18eFJaimdjvgSChsrlSEmTDDsoo5Q","expires_in":300,"refresh_expires_in":1800,"refresh_token":"eyJhbGciOiJIUzI1NiIsInR5cCIgOiAiSldUIiwia2lkIiA6ICJhMzZlMGU0NC02MWNmLTQ5NmMtOGRlZi03NTkwNjQ5MzQzMjEifQ.eyJleHAiOjE1OTAzOTk1NzEsImlhdCI6MTU5MDM5Nzc3MSwianRpIjoiNmMxNTBiY2EtYmE5NC00NTgxLWEwODEtYjI2YzhhMmI5YmZmIiwiaXNzIjoiaHR0cDovL2F1dGguZGVtby5wcmFnbWF0aWNpbmR1c3RyaWVzLmRlL2F1dGgvcmVhbG1zL0lvVERCIiwiYXVkIjoiaHR0cDovL2F1dGguZGVtby5wcmFnbWF0aWNpbmR1c3RyaWVzLmRlL2F1dGgvcmVhbG1zL0lvVERCIiwic3ViIjoiYmEzMmU0NzEtYzc3Mi00YjMzLThkYTYtNmZlOGFjZGEwMDczIiwidHlwIjoiUmVmcmVzaCIsImF6cCI6ImlvdGRiIiwic2Vzc2lvbl9zdGF0ZSI6IjA2MGQyODYyLTE0ZWQtNDJmZS1iYWY3LThkMWY3ODQ2NTdmMSIsInNjb3BlIjoiZW1haWwgcHJvZmlsZSJ9.ayNpXdNX28qahodX1zowrMGiUCw2AodlHBQFqr8Ui7c","token_type":"bearer","not-before-policy":0,"session_state":"060d2862-14ed-42fe-baf7-8d1f784657f1","scope":"email profile"} -``` - -### 2.5 Cli 的批量操作 -当您想要通过脚本的方式通过 Cli / Shell 对 IoTDB 进行批量操作时，可以使用-e 参数。通过使用该参数，您可以在不进入客户端输入模式的情况下操作 IoTDB。 - -为了避免 SQL 语句和其他参数混淆，现在只支持-e 参数作为最后的参数使用。 - -针对 cli/Shell 工具的-e 参数用法如下： - -Linux 系统与 MacOS 指令： - -```shell -Shell > bash sbin/start-cli.sh -h {host} -p {rpcPort} -u {user} -pw {password} -e {sql for iotdb} -``` - -Windows 系统指令 -```shell -# V2.0.4.x 版本之前 -Shell > sbin\start-cli.bat -h {host} -p {rpcPort} -u {user} -pw {password} -e {sql for iotdb} - -# V2.0.4.x 版本及之后 -Shell > sbin\windows\start-cli.bat -h {host} -p {rpcPort} -u {user} -pw {password} -e {sql for iotdb} -``` - -在 Windows 环境下，-e 参数的 SQL 语句需要使用` `` `对于`" "`进行替换 - -为了更好的解释-e 参数的使用，可以参考下面在 Linux 上执行的例子。 - -假设用户希望对一个新启动的 IoTDB 进行如下操作： - -1. 创建名为 root.demo 的 database - -2. 创建名为 root.demo.s1 的时间序列 - -3. 向创建的时间序列中插入三个数据点 - -4. 查询验证数据是否插入成功 - -那么通过使用 cli/Shell 工具的 -e 参数，可以采用如下的脚本： - -```shell -# !/bin/bash - -host=127.0.0.1 -rpcPort=6667 -user=root -pass=root - -bash ./sbin/start-cli.sh -h ${host} -p ${rpcPort} -u ${user} -pw ${pass} -e "CREATE DATABASE root.demo" -bash ./sbin/start-cli.sh -h ${host} -p ${rpcPort} -u ${user} -pw ${pass} -e "create timeseries root.demo.s1 WITH DATATYPE=INT32, ENCODING=RLE" -bash ./sbin/start-cli.sh -h ${host} -p ${rpcPort} -u ${user} -pw ${pass} -e "insert into root.demo(timestamp,s1) values(1,10)" -bash ./sbin/start-cli.sh -h ${host} -p ${rpcPort} -u ${user} -pw ${pass} -e "insert into root.demo(timestamp,s1) values(2,11)" -bash ./sbin/start-cli.sh -h ${host} -p ${rpcPort} -u ${user} -pw ${pass} -e "insert into root.demo(timestamp,s1) values(3,12)" -bash ./sbin/start-cli.sh -h ${host} -p ${rpcPort} -u ${user} -pw ${pass} -e "select s1 from root.demo" -``` - -打印出来的结果显示如下，通过这种方式进行的操作与客户端的输入模式以及通过 JDBC 进行操作结果是一致的。 - -```shell - Shell > bash ./shell.sh -+-----------------------------+------------+ -| Time|root.demo.s1| -+-----------------------------+------------+ -|1970-01-01T08:00:00.001+08:00| 10| -|1970-01-01T08:00:00.002+08:00| 11| -|1970-01-01T08:00:00.003+08:00| 12| -+-----------------------------+------------+ -Total line number = 3 -It costs 0.267s -``` - -需要特别注意的是，在脚本中使用 -e 参数时要对特殊字符进行转义。 - +--> \ No newline at end of file diff --git a/src/zh/UserGuide/Master/Tree/Tools-System/CLI_apache.md b/src/zh/UserGuide/Master/Tree/Tools-System/CLI_apache.md new file mode 100644 index 000000000..1adf00af4 --- /dev/null +++ b/src/zh/UserGuide/Master/Tree/Tools-System/CLI_apache.md @@ -0,0 +1,288 @@ + + +# 命令行工具 + +IOTDB 为用户提供 cli/Shell 工具用于启动客户端和服务端程序。下面介绍每个 cli/Shell 工具的运行方式和相关参数。 +> \$IOTDB\_HOME 表示 IoTDB 的安装目录所在路径。 + +## 1. 安装 +如果使用源码版，可以在 iotdb 的根目录下执行 + +```shell +> mvn clean package -pl cli -am -DskipTests +``` + +在生成完毕之后，IoTDB 的 Cli 工具位于文件夹"cli/target/iotdb-cli-{project.version}"中。 + +如果你下载的是二进制版，那么 Cli 可以在 sbin 文件夹下直接找到。 + +## 2. 运行 + +### 2.1 Cli 运行方式 +安装后的 IoTDB 中有一个默认用户：`root`，默认密码为`root`。用户可以使用该用户尝试运行 IoTDB 客户端以测试服务器是否正常启动。客户端启动脚本为$IOTDB_HOME/sbin 文件夹下的`start-cli`脚本。启动脚本时需要指定运行 IP 和 RPC PORT。以下为服务器在本机启动，且用户未更改运行端口号的示例，默认端口为 6667。若用户尝试连接远程服务器或更改了服务器运行的端口号，请在-h 和-p 项处使用服务器的 IP 和 RPC PORT。
+用户也可以在启动脚本的最前方设置自己的环境变量，如 JAVA_HOME 等。 + +Linux 系统与 MacOS 系统启动命令如下： + +```shell +Shell > bash sbin/start-cli.sh -h 127.0.0.1 -p 6667 -u root -pw root +``` +Windows 系统启动命令如下： + +```shell +# V2.0.4.x 版本之前 +Shell > sbin\start-cli.bat -h 127.0.0.1 -p 6667 -u root -pw root + +# V2.0.4.x 版本及之后 +Shell > sbin\windows\start-cli.bat -h 127.0.0.1 -p 6667 -u root -pw root +``` +回车后即可成功启动客户端。启动后出现如图提示即为启动成功。 + +``` + _____ _________ ______ ______ +|_ _| | _ _ ||_ _ `.|_ _ \ + | | .--.|_/ | | \_| | | `. \ | |_) | + | | / .'`\ \ | | | | | | | __'. + _| |_| \__. | _| |_ _| |_.' /_| |__) | +|_____|'.__.' |_____| |______.'|_______/ version + +Successfully login at 127.0.0.1:6667 +``` +输入`quit`或`exit`可退出 cli 结束本次会话，cli 输出`quit normally`表示退出成功。 + +### 2.2 Cli 运行参数 + +|参数名|参数类型|是否为必需参数| 说明| 例子 | +|:---|:---|:---|:---|:---| +|-disableISO8601 |没有参数 | 否 |如果设置了这个参数，IoTDB 将以数字的形式打印时间戳 (timestamp)。|-disableISO8601| +|-h <`host`> |string 类型，不需要引号|是|IoTDB 客户端连接 IoTDB 服务器的 IP 地址。|-h 10.129.187.21| +|-help|没有参数|否|打印 IoTDB 的帮助信息|-help| +|-p <`rpcPort`>|int 类型|是|IoTDB 连接服务器的端口号，IoTDB 默认运行在 6667 端口。|-p 6667| +|-pw <`password`>|string 类型，不需要引号|否|IoTDB 连接服务器所使用的密码。如果没有输入密码 IoTDB 会在 Cli 端提示输入密码。|-pw root| +|-u <`username`>|string 类型，不需要引号|是|IoTDB 连接服务器锁使用的用户名。|-u root| +|-maxPRC <`maxPrintRowCount`>|int 类型|否|设置 IoTDB 返回客户端命令行中所显示的最大行数。|-maxPRC 10| +|-e <`execute`> |string 类型|否|在不进入客户端输入模式的情况下，批量操作 IoTDB|-e "show databases"| +|-c | 空 | 否 | 如果服务器设置了 `rpc_thrift_compression_enable=true`, 则 CLI 必须使用 `-c` | -c | + +下面展示一条客户端命令，功能是连接 IP 为 10.129.187.21 的主机，端口为 6667 ，用户名为 root，密码为 root，以数字的形式打印时间戳，IoTDB 命令行显示的最大行数为 10。 + +Linux 系统与 MacOS 系统启动命令如下： + +```shell +Shell > bash sbin/start-cli.sh -h 10.129.187.21 -p 6667 -u root -pw root -disableISO8601 -maxPRC 10 +``` +Windows 系统启动命令如下： + +```shell +# V2.0.4.x 版本之前 +Shell > sbin\start-cli.bat -h 10.129.187.21 -p 6667 -u root -pw root -disableISO8601 -maxPRC 10 + +# V2.0.4.x 版本及之后 +Shell > sbin\windows\start-cli.bat -h 10.129.187.21 -p 6667 -u root -pw root -disableISO8601 -maxPRC 10 +``` + +### 2.3 CLI 特殊命令 +下面列举了一些CLI的特殊命令。 + +| 命令 | 描述 / 例子 | +|:---|:---| +| `set time_display_type=xxx` | 例如： long, default, ISO8601, yyyy-MM-dd HH:mm:ss | +| `show time_display_type` | 显示时间显示方式 | +| `set time_zone=xxx` | 例如： +08:00, Asia/Shanghai | +| `show time_zone` | 显示CLI的时区 | +| `set fetch_size=xxx` | 设置从服务器查询数据时的读取条数 | +| `show fetch_size` | 显示读取条数的大小 | +| `set max_display_num=xxx` | 设置 CLI 一次展示的最大数据条数， 设置为-1表示无限制 | +| `help` | 获取CLI特殊命令的提示 | +| `exit/quit` | 退出CLI | + +### 2.4 使用 OpenID 作为用户名认证登录 + +OpenID Connect (OIDC) 使用 keycloack 作为 OIDC 服务权限认证服务。 + +#### 配置 +配置位于 iotdb-system.properties，设定 authorizer_provider_class 为 org.apache.iotdb.commons.auth.authorizer.OpenIdAuthorizer 则开启了 openID 服务，默认情况下值为 org.apache.iotdb.commons.auth.authorizer.LocalFileAuthorizer 表示没有开启 openID 服务。 + +``` +authorizer_provider_class=org.apache.iotdb.commons.auth.authorizer.OpenIdAuthorizer +``` +如果开启了 openID 服务则 openID_url 为必填项，openID_url 值为 http://ip:port/realms/{realmsName} + +``` +openID_url=http://127.0.0.1:8080/realms/iotdb/ +``` +#### keycloack 配置 + +1、下载 keycloack 程序（此教程为21.1.0版本），在 keycloack/bin 中启动 keycloack + +```shell +Shell > cd bin +Shell > ./kc.sh start-dev +``` +2、使用 https://ip:port 登陆 keycloack, 首次登陆需要创建用户 + +![avatar](/img/UserGuide/CLI/Command-Line-Interface/login_keycloak.png?raw=true) + +3、点击 Administration Console 进入管理端 + +![avatar](/img/UserGuide/CLI/Command-Line-Interface/AdministrationConsole.png?raw=true) + +4、在左侧的 Master 菜单点击 Create Realm, 输入 Realm Name 创建一个新的 Realm + +![avatar](/img/UserGuide/CLI/Command-Line-Interface/add_Realm_1.jpg?raw=true) + +![avatar](/img/UserGuide/CLI/Command-Line-Interface/add_Realm_2.jpg?raw=true) + +5、点击左侧菜单 Clients，创建 client + +![avatar](/img/UserGuide/CLI/Command-Line-Interface/client.jpg?raw=true) + +6、点击左侧菜单 User，创建 user + +![avatar](/img/UserGuide/CLI/Command-Line-Interface/user.jpg?raw=true) + +7、点击新创建的用户 id，点击 Credentials 导航输入密码和关闭 Temporary 选项，至此 keyclork 配置完成 + +![avatar](/img/UserGuide/CLI/Command-Line-Interface/pwd.jpg?raw=true) + +8、创建角色，点击左侧菜单的 Roles然后点击Create Role 按钮添加角色 + +![avatar](/img/UserGuide/CLI/Command-Line-Interface/add_role1.jpg?raw=true) + +9、在Role Name 中输入`iotdb_admin`，点击save 按钮。提示：这里的`iotdb_admin`不能为其他名称否则即使登陆成功后也将无权限使用iotdb的查询、插入、创建 database、添加用户、角色等功能 + +![avatar](/img/UserGuide/CLI/Command-Line-Interface/add_role2.jpg?raw=true) + +10、点击左侧的User 菜单然后点击用户列表中的用户为该用户添加我们刚创建的`iotdb_admin`角色 + +![avatar](/img/UserGuide/CLI/Command-Line-Interface/add_role3.jpg?raw=true) + +11、选择Role Mappings ，在Assign role选择`iotdb_admin`增加角色 + +![avatar](/img/UserGuide/CLI/Command-Line-Interface/add_role4.jpg?raw=true) + +![avatar](/img/UserGuide/CLI/Command-Line-Interface/add_role5.jpg?raw=true) + +提示：如果用户角色有调整需要重新生成token并且重新登陆iotdb才会生效 + +以上步骤提供了一种 keycloak 登陆 iotdb 方式，更多方式请参考 keycloak 配置 + +若对应的 IoTDB 服务器开启了使用 OpenID Connect (OIDC) 作为权限认证服务，那么就不再需要使用用户名密码进行登录。 +替而代之的是使用 Token，以及空密码。 +此时，登录命令如下： + +```shell +Shell > bash sbin/start-cli.sh -h 10.129.187.21 -p 6667 -u {my-access-token} -pw "" +``` + +其中，需要将{my-access-token} （注意，包括{}）替换成你的 token，即 access_token 对应的值。密码为空需要再次确认。 + +![avatar](/img/UserGuide/CLI/Command-Line-Interface/iotdbpw.jpeg?raw=true) + +如何获取 token 取决于你的 OIDC 设置。 最简单的一种情况是使用`password-grant`。例如，假设你在用 keycloack 作为你的 OIDC 服务， +并且你在 keycloack 中有一个被定义成 public 的`iotdb`客户的 realm，那么你可以使用如下`curl`命令获得 token。 +（注意例子中的{}和里面的内容需要替换成具体的服务器地址和 realm 名字）： +```shell +curl -X POST "http://{your-keycloack-server}/realms/{your-realm}/protocol/openid-connect/token" \ -H "Content-Type: application/x-www-form-urlencoded" \ + -d "username={username}" \ + -d "password={password}" \ + -d 'grant_type=password' \ + -d "client_id=iotdb-client" +``` + +示例结果如下： + +```json +{"access_token":"eyJhbGciOiJSUzI1NiIsInR5cCIgOiAiSldUIiwia2lkIiA6ICJxMS1XbTBvelE1TzBtUUg4LVNKYXAyWmNONE1tdWNXd25RV0tZeFpKNG93In0.eyJleHAiOjE1OTAzOTgwNzEsImlhdCI6MTU5MDM5Nzc3MSwianRpIjoiNjA0ZmYxMDctN2NiNy00NTRmLWIwYmQtY2M2ZDQwMjFiNGU4IiwiaXNzIjoiaHR0cDovL2F1dGguZGVtby5wcmFnbWF0aWNpbmR1c3RyaWVzLmRlL2F1dGgvcmVhbG1zL0lvVERCIiwiYXVkIjoiYWNjb3VudCIsInN1YiI6ImJhMzJlNDcxLWM3NzItNGIzMy04ZGE2LTZmZThhY2RhMDA3MyIsInR5cCI6IkJlYXJlciIsImF6cCI6ImlvdGRiIiwic2Vzc2lvbl9zdGF0ZSI6IjA2MGQyODYyLTE0ZWQtNDJmZS1iYWY3LThkMWY3ODQ2NTdmMSIsImFjciI6IjEiLCJhbGxvd2VkLW9yaWdpbnMiOlsibG9jYWxob3N0OjgwODAiXSwicmVhbG1fYWNjZXNzIjp7InJvbGVzIjpbIm9mZmxpbmVfYWNjZXNzIiwidW1hX2F1dGhvcml6YXRpb24iLCJpb3RkYl9hZG1pbiJdfSwicmVzb3VyY2VfYWNjZXNzIjp7ImFjY291bnQiOnsicm9sZXMiOlsibWFuYWdlLWFjY291bnQiLCJtYW5hZ2UtYWNjb3VudC1saW5rcyIsInZpZXctcHJvZmlsZSJdfX0sInNjb3BlIjoiZW1haWwgcHJvZmlsZSIsImVtYWlsX3ZlcmlmaWVkIjp0cnVlLCJwcmVmZXJyZWRfdXNlcm5hbWUiOiJ1c2VyIn0.nwbrJkWdCNjzFrTDwKNuV5h9dDMg5ytRKGOXmFIajpfsbOutJytjWTCB2WpA8E1YI3KM6gU6Jx7cd7u0oPo5syHhfCz119n_wBiDnyTZkFOAPsx0M2z20kvBLN9k36_VfuCMFUeddJjO31MeLTmxB0UKg2VkxdczmzMH3pnalhxqpnWWk3GnrRrhAf2sZog0foH4Ae3Ks0lYtYzaWK_Yo7E4Px42-gJpohy3JevOC44aJ4auzJR1RBj9LUbgcRinkBy0JLi6XXiYznSC2V485CSBHW3sseXn7pSXQADhnmGQrLfFGO5ZljmPO18eFJaimdjvgSChsrlSEmTDDsoo5Q","expires_in":300,"refresh_expires_in":1800,"refresh_token":"eyJhbGciOiJIUzI1NiIsInR5cCIgOiAiSldUIiwia2lkIiA6ICJhMzZlMGU0NC02MWNmLTQ5NmMtOGRlZi03NTkwNjQ5MzQzMjEifQ.eyJleHAiOjE1OTAzOTk1NzEsImlhdCI6MTU5MDM5Nzc3MSwianRpIjoiNmMxNTBiY2EtYmE5NC00NTgxLWEwODEtYjI2YzhhMmI5YmZmIiwiaXNzIjoiaHR0cDovL2F1dGguZGVtby5wcmFnbWF0aWNpbmR1c3RyaWVzLmRlL2F1dGgvcmVhbG1zL0lvVERCIiwiYXVkIjoiaHR0cDovL2F1dGguZGVtby5wcmFnbWF0aWNpbmR1c3RyaWVzLmRlL2F1dGgvcmVhbG1zL0lvVERCIiwic3ViIjoiYmEzMmU0NzEtYzc3Mi00YjMzLThkYTYtNmZlOGFjZGEwMDczIiwidHlwIjoiUmVmcmVzaCIsImF6cCI6ImlvdGRiIiwic2Vzc2lvbl9zdGF0ZSI6IjA2MGQyODYyLTE0ZWQtNDJmZS1iYWY3LThkMWY3ODQ2NTdmMSIsInNjb3BlIjoiZW1haWwgcHJvZmlsZSJ9.ayNpXdNX28qahodX1zowrMGiUCw2AodlHBQFqr8Ui7c","token_type":"bearer","not-before-policy":0,"session_state":"060d2862-14ed-42fe-baf7-8d1f784657f1","scope":"email profile"} +``` + +### 2.5 Cli 的批量操作 +当您想要通过脚本的方式通过 Cli / Shell 对 IoTDB 进行批量操作时，可以使用-e 参数。通过使用该参数，您可以在不进入客户端输入模式的情况下操作 IoTDB。 + +为了避免 SQL 语句和其他参数混淆，现在只支持-e 参数作为最后的参数使用。 + +针对 cli/Shell 工具的-e 参数用法如下： + +Linux 系统与 MacOS 指令： + +```shell +Shell > bash sbin/start-cli.sh -h {host} -p {rpcPort} -u {user} -pw {password} -e {sql for iotdb} +``` + +Windows 系统指令 +```shell +# V2.0.4.x 版本之前 +Shell > sbin\start-cli.bat -h {host} -p {rpcPort} -u {user} -pw {password} -e {sql for iotdb} + +# V2.0.4.x 版本及之后 +Shell > sbin\windows\start-cli.bat -h {host} -p {rpcPort} -u {user} -pw {password} -e {sql for iotdb} +``` + +在 Windows 环境下，-e 参数的 SQL 语句需要使用` `` `对于`" "`进行替换 + +为了更好的解释-e 参数的使用，可以参考下面在 Linux 上执行的例子。 + +假设用户希望对一个新启动的 IoTDB 进行如下操作： + +1. 创建名为 root.demo 的 database + +2. 创建名为 root.demo.s1 的时间序列 + +3. 向创建的时间序列中插入三个数据点 + +4. 查询验证数据是否插入成功 + +那么通过使用 cli/Shell 工具的 -e 参数，可以采用如下的脚本： + +```shell +# !/bin/bash + +host=127.0.0.1 +rpcPort=6667 +user=root +pass=root + +bash ./sbin/start-cli.sh -h ${host} -p ${rpcPort} -u ${user} -pw ${pass} -e "CREATE DATABASE root.demo" +bash ./sbin/start-cli.sh -h ${host} -p ${rpcPort} -u ${user} -pw ${pass} -e "create timeseries root.demo.s1 WITH DATATYPE=INT32, ENCODING=RLE" +bash ./sbin/start-cli.sh -h ${host} -p ${rpcPort} -u ${user} -pw ${pass} -e "insert into root.demo(timestamp,s1) values(1,10)" +bash ./sbin/start-cli.sh -h ${host} -p ${rpcPort} -u ${user} -pw ${pass} -e "insert into root.demo(timestamp,s1) values(2,11)" +bash ./sbin/start-cli.sh -h ${host} -p ${rpcPort} -u ${user} -pw ${pass} -e "insert into root.demo(timestamp,s1) values(3,12)" +bash ./sbin/start-cli.sh -h ${host} -p ${rpcPort} -u ${user} -pw ${pass} -e "select s1 from root.demo" +``` + +打印出来的结果显示如下，通过这种方式进行的操作与客户端的输入模式以及通过 JDBC 进行操作结果是一致的。 + +```shell + Shell > bash ./shell.sh ++-----------------------------+------------+ +| Time|root.demo.s1| ++-----------------------------+------------+ +|1970-01-01T08:00:00.001+08:00| 10| +|1970-01-01T08:00:00.002+08:00| 11| +|1970-01-01T08:00:00.003+08:00| 12| ++-----------------------------+------------+ +Total line number = 3 +It costs 0.267s +``` + +需要特别注意的是，在脚本中使用 -e 参数时要对特殊字符进行转义。 + diff --git a/src/zh/UserGuide/Master/Tree/Tools-System/CLI_timecho.md b/src/zh/UserGuide/Master/Tree/Tools-System/CLI_timecho.md new file mode 100644 index 000000000..c3d9f570f --- /dev/null +++ b/src/zh/UserGuide/Master/Tree/Tools-System/CLI_timecho.md @@ -0,0 +1,275 @@ + + +# 命令行工具 + +IOTDB 为用户提供 cli/Shell 工具用于启动客户端和服务端程序。下面介绍每个 cli/Shell 工具的运行方式和相关参数。 +> \$IOTDB\_HOME 表示 IoTDB 的安装目录所在路径。 + +## 1. Cli 运行方式 +安装后的 IoTDB 中有一个默认用户：`root`，默认密码为`root`。用户可以使用该用户尝试运行 IoTDB 客户端以测试服务器是否正常启动。客户端启动脚本为$IOTDB_HOME/sbin 文件夹下的`start-cli`脚本。启动脚本时需要指定运行 IP 和 RPC PORT。以下为服务器在本机启动，且用户未更改运行端口号的示例，默认端口为 6667。若用户尝试连接远程服务器或更改了服务器运行的端口号，请在-h 和-p 项处使用服务器的 IP 和 RPC PORT。
+用户也可以在启动脚本的最前方设置自己的环境变量，如 JAVA_HOME 等。 + +Linux 系统与 MacOS 系统启动命令如下： + +```shell +Shell > bash sbin/start-cli.sh -h 127.0.0.1 -p 6667 -u root -pw root +``` +Windows 系统启动命令如下： + +```shell +# V2.0.4.x 版本之前 +Shell > sbin\start-cli.bat -h 127.0.0.1 -p 6667 -u root -pw root + +# V2.0.4.x 版本及之后 +Shell > sbin\windows\start-cli.bat -h 127.0.0.1 -p 6667 -u root -pw root +``` +回车后即可成功启动客户端。启动后出现如图提示即为启动成功。 + +``` + _____ _________ ______ ______ +|_ _| | _ _ ||_ _ `.|_ _ \ + | | .--.|_/ | | \_| | | `. \ | |_) | + | | / .'`\ \ | | | | | | | __'. + _| |_| \__. | _| |_ _| |_.' /_| |__) | +|_____|'.__.' |_____| |______.'|_______/ version + +Successfully login at 127.0.0.1:6667 +``` +输入`quit`或`exit`可退出 cli 结束本次会话，cli 输出`quit normally`表示退出成功。 + +## 2. Cli 运行参数 + +|参数名|参数类型|是否为必需参数| 说明| 例子 | +|:---|:---|:---|:---|:---| +|-disableISO8601 |没有参数 | 否 |如果设置了这个参数，IoTDB 将以数字的形式打印时间戳 (timestamp)。|-disableISO8601| +|-h <`host`> |string 类型，不需要引号|是|IoTDB 客户端连接 IoTDB 服务器的 IP 地址。|-h 10.129.187.21| +|-help|没有参数|否|打印 IoTDB 的帮助信息|-help| +|-p <`rpcPort`>|int 类型|是|IoTDB 连接服务器的端口号，IoTDB 默认运行在 6667 端口。|-p 6667| +|-pw <`password`>|string 类型，不需要引号|否|IoTDB 连接服务器所使用的密码。如果没有输入密码 IoTDB 会在 Cli 端提示输入密码。|-pw root| +|-u <`username`>|string 类型，不需要引号|是|IoTDB 连接服务器锁使用的用户名。|-u root| +|-maxPRC <`maxPrintRowCount`>|int 类型|否|设置 IoTDB 返回客户端命令行中所显示的最大行数。|-maxPRC 10| +|-e <`execute`> |string 类型|否|在不进入客户端输入模式的情况下，批量操作 IoTDB|-e "show databases"| +|-c | 空 | 否 | 如果服务器设置了 `rpc_thrift_compression_enable=true`, 则 CLI 必须使用 `-c` | -c | + +下面展示一条客户端命令，功能是连接 IP 为 10.129.187.21 的主机，端口为 6667 ，用户名为 root，密码为 root，以数字的形式打印时间戳，IoTDB 命令行显示的最大行数为 10。 + +Linux 系统与 MacOS 系统启动命令如下： + +```shell +Shell > bash sbin/start-cli.sh -h 10.129.187.21 -p 6667 -u root -pw root -disableISO8601 -maxPRC 10 +``` +Windows 系统启动命令如下： + +```shell +# V2.0.4.x 版本之前 +Shell > sbin\start-cli.bat -h 10.129.187.21 -p 6667 -u root -pw root -disableISO8601 -maxPRC 10 + +# V2.0.4.x 版本及之后 +Shell > sbin\windows\start-cli.bat -h 10.129.187.21 -p 6667 -u root -pw root -disableISO8601 -maxPRC 10 +``` + +## 3. CLI 特殊命令 +下面列举了一些CLI的特殊命令。 + +| 命令 | 描述 / 例子 | +|:---|:---| +| `set time_display_type=xxx` | 例如： long, default, ISO8601, yyyy-MM-dd HH:mm:ss | +| `show time_display_type` | 显示时间显示方式 | +| `set time_zone=xxx` | 例如： +08:00, Asia/Shanghai | +| `show time_zone` | 显示CLI的时区 | +| `set fetch_size=xxx` | 设置从服务器查询数据时的读取条数 | +| `show fetch_size` | 显示读取条数的大小 | +| `set max_display_num=xxx` | 设置 CLI 一次展示的最大数据条数， 设置为-1表示无限制 | +| `help` | 获取CLI特殊命令的提示 | +| `exit/quit` | 退出CLI | + +## 4. 使用 OpenID 作为用户名认证登录 + +OpenID Connect (OIDC) 使用 keycloack 作为 OIDC 服务权限认证服务。 + +### 配置 +配置位于 iotdb-system.properties，设定 authorizer_provider_class 为 org.apache.iotdb.commons.auth.authorizer.OpenIdAuthorizer 则开启了 openID 服务，默认情况下值为 org.apache.iotdb.commons.auth.authorizer.LocalFileAuthorizer 表示没有开启 openID 服务。 + +``` +authorizer_provider_class=org.apache.iotdb.commons.auth.authorizer.OpenIdAuthorizer +``` +如果开启了 openID 服务则 openID_url 为必填项，openID_url 值为 http://ip:port/realms/{realmsName} + +``` +openID_url=http://127.0.0.1:8080/realms/iotdb/ +``` +### keycloack 配置 + +1、下载 keycloack 程序（此教程为21.1.0版本），在 keycloack/bin 中启动 keycloack + +```shell +Shell > cd bin +Shell > ./kc.sh start-dev +``` +2、使用 https://ip:port 登陆 keycloack, 首次登陆需要创建用户 + +![avatar](/img/UserGuide/CLI/Command-Line-Interface/login_keycloak.png?raw=true) + +3、点击 Administration Console 进入管理端 + +![avatar](/img/UserGuide/CLI/Command-Line-Interface/AdministrationConsole.png?raw=true) + +4、在左侧的 Master 菜单点击 Create Realm, 输入 Realm Name 创建一个新的 Realm + +![avatar](/img/UserGuide/CLI/Command-Line-Interface/add_Realm_1.jpg?raw=true) + +![avatar](/img/UserGuide/CLI/Command-Line-Interface/add_Realm_2.jpg?raw=true) + +5、点击左侧菜单 Clients，创建 client + +![avatar](/img/UserGuide/CLI/Command-Line-Interface/client.jpg?raw=true) + +6、点击左侧菜单 User，创建 user + +![avatar](/img/UserGuide/CLI/Command-Line-Interface/user.jpg?raw=true) + +7、点击新创建的用户 id，点击 Credentials 导航输入密码和关闭 Temporary 选项，至此 keyclork 配置完成 + +![avatar](/img/UserGuide/CLI/Command-Line-Interface/pwd.jpg?raw=true) + +8、创建角色，点击左侧菜单的 Roles然后点击Create Role 按钮添加角色 + +![avatar](/img/UserGuide/CLI/Command-Line-Interface/add_role1.jpg?raw=true) + +9、在Role Name 中输入`iotdb_admin`，点击save 按钮。提示：这里的`iotdb_admin`不能为其他名称否则即使登陆成功后也将无权限使用iotdb的查询、插入、创建 database、添加用户、角色等功能 + +![avatar](/img/UserGuide/CLI/Command-Line-Interface/add_role2.jpg?raw=true) + +10、点击左侧的User 菜单然后点击用户列表中的用户为该用户添加我们刚创建的`iotdb_admin`角色 + +![avatar](/img/UserGuide/CLI/Command-Line-Interface/add_role3.jpg?raw=true) + +11、选择Role Mappings ，在Assign role选择`iotdb_admin`增加角色 + +![avatar](/img/UserGuide/CLI/Command-Line-Interface/add_role4.jpg?raw=true) + +![avatar](/img/UserGuide/CLI/Command-Line-Interface/add_role5.jpg?raw=true) + +提示：如果用户角色有调整需要重新生成token并且重新登陆iotdb才会生效 + +以上步骤提供了一种 keycloak 登陆 iotdb 方式，更多方式请参考 keycloak 配置 + +若对应的 IoTDB 服务器开启了使用 OpenID Connect (OIDC) 作为权限认证服务，那么就不再需要使用用户名密码进行登录。 +替而代之的是使用 Token，以及空密码。 +此时，登录命令如下： + +```shell +Shell > bash sbin/start-cli.sh -h 10.129.187.21 -p 6667 -u {my-access-token} -pw "" +``` + +其中，需要将{my-access-token} （注意，包括{}）替换成你的 token，即 access_token 对应的值。密码为空需要再次确认。 + +![avatar](/img/UserGuide/CLI/Command-Line-Interface/iotdbpw.jpeg?raw=true) + +如何获取 token 取决于你的 OIDC 设置。 最简单的一种情况是使用`password-grant`。例如，假设你在用 keycloack 作为你的 OIDC 服务， +并且你在 keycloack 中有一个被定义成 public 的`iotdb`客户的 realm，那么你可以使用如下`curl`命令获得 token。 +（注意例子中的{}和里面的内容需要替换成具体的服务器地址和 realm 名字）： +```shell +curl -X POST "http://{your-keycloack-server}/realms/{your-realm}/protocol/openid-connect/token" \ -H "Content-Type: application/x-www-form-urlencoded" \ + -d "username={username}" \ + -d "password={password}" \ + -d 'grant_type=password' \ + -d "client_id=iotdb-client" +``` + +示例结果如下： + +```json +{"access_token":"eyJhbGciOiJSUzI1NiIsInR5cCIgOiAiSldUIiwia2lkIiA6ICJxMS1XbTBvelE1TzBtUUg4LVNKYXAyWmNONE1tdWNXd25RV0tZeFpKNG93In0.eyJleHAiOjE1OTAzOTgwNzEsImlhdCI6MTU5MDM5Nzc3MSwianRpIjoiNjA0ZmYxMDctN2NiNy00NTRmLWIwYmQtY2M2ZDQwMjFiNGU4IiwiaXNzIjoiaHR0cDovL2F1dGguZGVtby5wcmFnbWF0aWNpbmR1c3RyaWVzLmRlL2F1dGgvcmVhbG1zL0lvVERCIiwiYXVkIjoiYWNjb3VudCIsInN1YiI6ImJhMzJlNDcxLWM3NzItNGIzMy04ZGE2LTZmZThhY2RhMDA3MyIsInR5cCI6IkJlYXJlciIsImF6cCI6ImlvdGRiIiwic2Vzc2lvbl9zdGF0ZSI6IjA2MGQyODYyLTE0ZWQtNDJmZS1iYWY3LThkMWY3ODQ2NTdmMSIsImFjciI6IjEiLCJhbGxvd2VkLW9yaWdpbnMiOlsibG9jYWxob3N0OjgwODAiXSwicmVhbG1fYWNjZXNzIjp7InJvbGVzIjpbIm9mZmxpbmVfYWNjZXNzIiwidW1hX2F1dGhvcml6YXRpb24iLCJpb3RkYl9hZG1pbiJdfSwicmVzb3VyY2VfYWNjZXNzIjp7ImFjY291bnQiOnsicm9sZXMiOlsibWFuYWdlLWFjY291bnQiLCJtYW5hZ2UtYWNjb3VudC1saW5rcyIsInZpZXctcHJvZmlsZSJdfX0sInNjb3BlIjoiZW1haWwgcHJvZmlsZSIsImVtYWlsX3ZlcmlmaWVkIjp0cnVlLCJwcmVmZXJyZWRfdXNlcm5hbWUiOiJ1c2VyIn0.nwbrJkWdCNjzFrTDwKNuV5h9dDMg5ytRKGOXmFIajpfsbOutJytjWTCB2WpA8E1YI3KM6gU6Jx7cd7u0oPo5syHhfCz119n_wBiDnyTZkFOAPsx0M2z20kvBLN9k36_VfuCMFUeddJjO31MeLTmxB0UKg2VkxdczmzMH3pnalhxqpnWWk3GnrRrhAf2sZog0foH4Ae3Ks0lYtYzaWK_Yo7E4Px42-gJpohy3JevOC44aJ4auzJR1RBj9LUbgcRinkBy0JLi6XXiYznSC2V485CSBHW3sseXn7pSXQADhnmGQrLfFGO5ZljmPO18eFJaimdjvgSChsrlSEmTDDsoo5Q","expires_in":300,"refresh_expires_in":1800,"refresh_token":"eyJhbGciOiJIUzI1NiIsInR5cCIgOiAiSldUIiwia2lkIiA6ICJhMzZlMGU0NC02MWNmLTQ5NmMtOGRlZi03NTkwNjQ5MzQzMjEifQ.eyJleHAiOjE1OTAzOTk1NzEsImlhdCI6MTU5MDM5Nzc3MSwianRpIjoiNmMxNTBiY2EtYmE5NC00NTgxLWEwODEtYjI2YzhhMmI5YmZmIiwiaXNzIjoiaHR0cDovL2F1dGguZGVtby5wcmFnbWF0aWNpbmR1c3RyaWVzLmRlL2F1dGgvcmVhbG1zL0lvVERCIiwiYXVkIjoiaHR0cDovL2F1dGguZGVtby5wcmFnbWF0aWNpbmR1c3RyaWVzLmRlL2F1dGgvcmVhbG1zL0lvVERCIiwic3ViIjoiYmEzMmU0NzEtYzc3Mi00YjMzLThkYTYtNmZlOGFjZGEwMDczIiwidHlwIjoiUmVmcmVzaCIsImF6cCI6ImlvdGRiIiwic2Vzc2lvbl9zdGF0ZSI6IjA2MGQyODYyLTE0ZWQtNDJmZS1iYWY3LThkMWY3ODQ2NTdmMSIsInNjb3BlIjoiZW1haWwgcHJvZmlsZSJ9.ayNpXdNX28qahodX1zowrMGiUCw2AodlHBQFqr8Ui7c","token_type":"bearer","not-before-policy":0,"session_state":"060d2862-14ed-42fe-baf7-8d1f784657f1","scope":"email profile"} +``` + +## 5. Cli 的批量操作 +当您想要通过脚本的方式通过 Cli / Shell 对 IoTDB 进行批量操作时，可以使用-e 参数。通过使用该参数，您可以在不进入客户端输入模式的情况下操作 IoTDB。 + +为了避免 SQL 语句和其他参数混淆，现在只支持-e 参数作为最后的参数使用。 + +针对 cli/Shell 工具的-e 参数用法如下： + +Linux 系统与 MacOS 指令： + +```shell +Shell > bash sbin/start-cli.sh -h {host} -p {rpcPort} -u {user} -pw {password} -e {sql for iotdb} +``` + +Windows 系统指令 +```shell +# V2.0.4.x 版本之前 +Shell > sbin\start-cli.bat -h {host} -p {rpcPort} -u {user} -pw {password} -e {sql for iotdb} + +# V2.0.4.x 版本及之后 +Shell > sbin\windows\start-cli.bat -h {host} -p {rpcPort} -u {user} -pw {password} -e {sql for iotdb} +``` + +在 Windows 环境下，-e 参数的 SQL 语句需要使用` `` `对于`" "`进行替换 + +为了更好的解释-e 参数的使用，可以参考下面在 Linux 上执行的例子。 + +假设用户希望对一个新启动的 IoTDB 进行如下操作： + +1. 创建名为 root.demo 的 database + +2. 创建名为 root.demo.s1 的时间序列 + +3. 向创建的时间序列中插入三个数据点 + +4. 查询验证数据是否插入成功 + +那么通过使用 cli/Shell 工具的 -e 参数，可以采用如下的脚本： + +```shell +# !/bin/bash + +host=127.0.0.1 +rpcPort=6667 +user=root +pass=root + +bash ./sbin/start-cli.sh -h ${host} -p ${rpcPort} -u ${user} -pw ${pass} -e "CREATE DATABASE root.demo" +bash ./sbin/start-cli.sh -h ${host} -p ${rpcPort} -u ${user} -pw ${pass} -e "create timeseries root.demo.s1 WITH DATATYPE=INT32, ENCODING=RLE" +bash ./sbin/start-cli.sh -h ${host} -p ${rpcPort} -u ${user} -pw ${pass} -e "insert into root.demo(timestamp,s1) values(1,10)" +bash ./sbin/start-cli.sh -h ${host} -p ${rpcPort} -u ${user} -pw ${pass} -e "insert into root.demo(timestamp,s1) values(2,11)" +bash ./sbin/start-cli.sh -h ${host} -p ${rpcPort} -u ${user} -pw ${pass} -e "insert into root.demo(timestamp,s1) values(3,12)" +bash ./sbin/start-cli.sh -h ${host} -p ${rpcPort} -u ${user} -pw ${pass} -e "select s1 from root.demo" +``` + +打印出来的结果显示如下，通过这种方式进行的操作与客户端的输入模式以及通过 JDBC 进行操作结果是一致的。 + +```shell + Shell > bash ./shell.sh ++-----------------------------+------------+ +| Time|root.demo.s1| ++-----------------------------+------------+ +|1970-01-01T08:00:00.001+08:00| 10| +|1970-01-01T08:00:00.002+08:00| 11| +|1970-01-01T08:00:00.003+08:00| 12| ++-----------------------------+------------+ +Total line number = 3 +It costs 0.267s +``` + +需要特别注意的是，在脚本中使用 -e 参数时要对特殊字符进行转义。 + diff --git a/src/zh/UserGuide/V1.3.x/Tools-System/CLI.md b/src/zh/UserGuide/V1.3.x/Tools-System/CLI.md index aaff80934..03580fafb 100644 --- a/src/zh/UserGuide/V1.3.x/Tools-System/CLI.md +++ b/src/zh/UserGuide/V1.3.x/Tools-System/CLI.md @@ -1,3 +1,6 @@ +--- +redirectTo: CLI_apache.html +--- - -# SQL 命令行终端 (CLI) - -IOTDB 为用户提供 cli/Shell 工具用于启动客户端和服务端程序。下面介绍每个 cli/Shell 工具的运行方式和相关参数。 -> \$IOTDB\_HOME 表示 IoTDB 的安装目录所在路径。 - -## 安装 -如果使用源码版，可以在 iotdb 的根目录下执行 - -```shell -> mvn clean package -pl cli -am -DskipTests -``` - -在生成完毕之后，IoTDB 的 Cli 工具位于文件夹"cli/target/iotdb-cli-{project.version}"中。 - -如果你下载的是二进制版，那么 Cli 可以在 sbin 文件夹下直接找到。 - -## 运行 - -### Cli 运行方式 -安装后的 IoTDB 中有一个默认用户：`root`，默认密码为`root`。用户可以使用该用户尝试运行 IoTDB 客户端以测试服务器是否正常启动。客户端启动脚本为$IOTDB_HOME/sbin 文件夹下的`start-cli`脚本。启动脚本时需要指定运行 IP 和 RPC PORT。以下为服务器在本机启动，且用户未更改运行端口号的示例，默认端口为 6667。若用户尝试连接远程服务器或更改了服务器运行的端口号，请在-h 和-p 项处使用服务器的 IP 和 RPC PORT。
-用户也可以在启动脚本的最前方设置自己的环境变量，如 JAVA_HOME 等 （对于 linux 用户，脚本路径为："/sbin/start-cli.sh"； 对于 windows 用户，脚本路径为："/sbin/start-cli.bat") - -Linux 系统与 MacOS 系统启动命令如下： - -```shell -Shell > bash sbin/start-cli.sh -h 127.0.0.1 -p 6667 -u root -pw root -``` -Windows 系统启动命令如下： - -```shell -Shell > sbin\start-cli.bat -h 127.0.0.1 -p 6667 -u root -pw root -``` -回车后即可成功启动客户端。启动后出现如图提示即为启动成功。 - -``` - _____ _________ ______ ______ -|_ _| | _ _ ||_ _ `.|_ _ \ - | | .--.|_/ | | \_| | | `. \ | |_) | - | | / .'`\ \ | | | | | | | __'. - _| |_| \__. | _| |_ _| |_.' /_| |__) | -|_____|'.__.' |_____| |______.'|_______/ version - -Successfully login at 127.0.0.1:6667 -``` -输入`quit`或`exit`可退出 cli 结束本次会话，cli 输出`quit normally`表示退出成功。 - -### Cli 运行参数 - -|参数名|参数类型|是否为必需参数| 说明| 例子 | -|:---|:---|:---|:---|:---| -|-disableISO8601 |没有参数 | 否 |如果设置了这个参数，IoTDB 将以数字的形式打印时间戳 (timestamp)。|-disableISO8601| -|-h <`host`> |string 类型，不需要引号|是|IoTDB 客户端连接 IoTDB 服务器的 IP 地址。|-h 10.129.187.21| -|-help|没有参数|否|打印 IoTDB 的帮助信息|-help| -|-p <`rpcPort`>|int 类型|是|IoTDB 连接服务器的端口号，IoTDB 默认运行在 6667 端口。|-p 6667| -|-pw <`password`>|string 类型，不需要引号|否|IoTDB 连接服务器所使用的密码。如果没有输入密码 IoTDB 会在 Cli 端提示输入密码。|-pw root| -|-u <`username`>|string 类型，不需要引号|是|IoTDB 连接服务器锁使用的用户名。|-u root| -|-maxPRC <`maxPrintRowCount`>|int 类型|否|设置 IoTDB 返回客户端命令行中所显示的最大行数。|-maxPRC 10| -|-e <`execute`> |string 类型|否|在不进入客户端输入模式的情况下，批量操作 IoTDB|-e "show databases"| -|-c | 空 | 否 | 如果服务器设置了 `rpc_thrift_compression_enable=true`, 则 CLI 必须使用 `-c` | -c | - -下面展示一条客户端命令，功能是连接 IP 为 10.129.187.21 的主机，端口为 6667 ，用户名为 root，密码为 root，以数字的形式打印时间戳，IoTDB 命令行显示的最大行数为 10。 - -Linux 系统与 MacOS 系统启动命令如下： - -```shell -Shell > bash sbin/start-cli.sh -h 10.129.187.21 -p 6667 -u root -pw root -disableISO8601 -maxPRC 10 -``` -Windows 系统启动命令如下： - -```shell -Shell > sbin\start-cli.bat -h 10.129.187.21 -p 6667 -u root -pw root -disableISO8601 -maxPRC 10 -``` - -### CLI 特殊命令 -下面列举了一些CLI的特殊命令。 - -| 命令 | 描述 / 例子 | -|:---|:---| -| `set time_display_type=xxx` | 例如： long, default, ISO8601, yyyy-MM-dd HH:mm:ss | -| `show time_display_type` | 显示时间显示方式 | -| `set time_zone=xxx` | 例如： +08:00, Asia/Shanghai | -| `show time_zone` | 显示CLI的时区 | -| `set fetch_size=xxx` | 设置从服务器查询数据时的读取条数 | -| `show fetch_size` | 显示读取条数的大小 | -| `set max_display_num=xxx` | 设置 CLI 一次展示的最大数据条数， 设置为-1表示无限制 | -| `help` | 获取CLI特殊命令的提示 | -| `exit/quit` | 退出CLI | - -### 使用 OpenID 作为用户名认证登录 - -OpenID Connect (OIDC) 使用 keycloack 作为 OIDC 服务权限认证服务。 - -#### 配置 -配置位于 iotdb-system.properties，设定 authorizer_provider_class 为 org.apache.iotdb.commons.auth.authorizer.OpenIdAuthorizer 则开启了 openID 服务，默认情况下值为 org.apache.iotdb.commons.auth.authorizer.LocalFileAuthorizer 表示没有开启 openID 服务。 - -``` -authorizer_provider_class=org.apache.iotdb.commons.auth.authorizer.OpenIdAuthorizer -``` -如果开启了 openID 服务则 openID_url 为必填项，openID_url 值为 http://ip:port/realms/{realmsName} - -``` -openID_url=http://127.0.0.1:8080/realms/iotdb/ -``` -####keycloack 配置 - -1、下载 keycloack 程序（此教程为21.1.0版本），在 keycloack/bin 中启动 keycloack - -```shell -Shell > cd bin -Shell > ./kc.sh start-dev -``` -2、使用 https://ip:port 登陆 keycloack, 首次登陆需要创建用户 - -![avatar](/img/UserGuide/CLI/Command-Line-Interface/login_keycloak.png?raw=true) - -3、点击 Administration Console 进入管理端 - -![avatar](/img/UserGuide/CLI/Command-Line-Interface/AdministrationConsole.png?raw=true) - -4、在左侧的 Master 菜单点击 Create Realm, 输入 Realm Name 创建一个新的 Realm - -![avatar](/img/UserGuide/CLI/Command-Line-Interface/add_Realm_1.jpg?raw=true) - -![avatar](/img/UserGuide/CLI/Command-Line-Interface/add_Realm_2.jpg?raw=true) - -5、点击左侧菜单 Clients，创建 client - -![avatar](/img/UserGuide/CLI/Command-Line-Interface/client.jpg?raw=true) - -6、点击左侧菜单 User，创建 user - -![avatar](/img/UserGuide/CLI/Command-Line-Interface/user.jpg?raw=true) - -7、点击新创建的用户 id，点击 Credentials 导航输入密码和关闭 Temporary 选项，至此 keyclork 配置完成 - -![avatar](/img/UserGuide/CLI/Command-Line-Interface/pwd.jpg?raw=true) - -8、创建角色，点击左侧菜单的 Roles然后点击Create Role 按钮添加角色 - -![avatar](/img/UserGuide/CLI/Command-Line-Interface/add_role1.jpg?raw=true) - -9、在Role Name 中输入`iotdb_admin`，点击save 按钮。提示：这里的`iotdb_admin`不能为其他名称否则即使登陆成功后也将无权限使用iotdb的查询、插入、创建 database、添加用户、角色等功能 - -![avatar](/img/UserGuide/CLI/Command-Line-Interface/add_role2.jpg?raw=true) - -10、点击左侧的User 菜单然后点击用户列表中的用户为该用户添加我们刚创建的`iotdb_admin`角色 - -![avatar](/img/UserGuide/CLI/Command-Line-Interface/add_role3.jpg?raw=true) - -11、选择Role Mappings ，在Assign role选择`iotdb_admin`增加角色 - -![avatar](/img/UserGuide/CLI/Command-Line-Interface/add_role4.jpg?raw=true) - -![avatar](/img/UserGuide/CLI/Command-Line-Interface/add_role5.jpg?raw=true) - -提示：如果用户角色有调整需要重新生成token并且重新登陆iotdb才会生效 - -以上步骤提供了一种 keycloak 登陆 iotdb 方式，更多方式请参考 keycloak 配置 - -若对应的 IoTDB 服务器开启了使用 OpenID Connect (OIDC) 作为权限认证服务，那么就不再需要使用用户名密码进行登录。 -替而代之的是使用 Token，以及空密码。 -此时，登录命令如下： - -```shell -Shell > bash sbin/start-cli.sh -h 10.129.187.21 -p 6667 -u {my-access-token} -pw "" -``` - -其中，需要将{my-access-token} （注意，包括{}）替换成你的 token，即 access_token 对应的值。密码为空需要再次确认。 - -![avatar](/img/UserGuide/CLI/Command-Line-Interface/iotdbpw.jpeg?raw=true) - -如何获取 token 取决于你的 OIDC 设置。 最简单的一种情况是使用`password-grant`。例如，假设你在用 keycloack 作为你的 OIDC 服务， -并且你在 keycloack 中有一个被定义成 public 的`iotdb`客户的 realm，那么你可以使用如下`curl`命令获得 token。 -（注意例子中的{}和里面的内容需要替换成具体的服务器地址和 realm 名字）： -```shell -curl -X POST "http://{your-keycloack-server}/realms/{your-realm}/protocol/openid-connect/token" \ -H "Content-Type: application/x-www-form-urlencoded" \ - -d "username={username}" \ - -d "password={password}" \ - -d 'grant_type=password' \ - -d "client_id=iotdb-client" -``` - -示例结果如下： - -```json -{"access_token":"eyJhbGciOiJSUzI1NiIsInR5cCIgOiAiSldUIiwia2lkIiA6ICJxMS1XbTBvelE1TzBtUUg4LVNKYXAyWmNONE1tdWNXd25RV0tZeFpKNG93In0.eyJleHAiOjE1OTAzOTgwNzEsImlhdCI6MTU5MDM5Nzc3MSwianRpIjoiNjA0ZmYxMDctN2NiNy00NTRmLWIwYmQtY2M2ZDQwMjFiNGU4IiwiaXNzIjoiaHR0cDovL2F1dGguZGVtby5wcmFnbWF0aWNpbmR1c3RyaWVzLmRlL2F1dGgvcmVhbG1zL0lvVERCIiwiYXVkIjoiYWNjb3VudCIsInN1YiI6ImJhMzJlNDcxLWM3NzItNGIzMy04ZGE2LTZmZThhY2RhMDA3MyIsInR5cCI6IkJlYXJlciIsImF6cCI6ImlvdGRiIiwic2Vzc2lvbl9zdGF0ZSI6IjA2MGQyODYyLTE0ZWQtNDJmZS1iYWY3LThkMWY3ODQ2NTdmMSIsImFjciI6IjEiLCJhbGxvd2VkLW9yaWdpbnMiOlsibG9jYWxob3N0OjgwODAiXSwicmVhbG1fYWNjZXNzIjp7InJvbGVzIjpbIm9mZmxpbmVfYWNjZXNzIiwidW1hX2F1dGhvcml6YXRpb24iLCJpb3RkYl9hZG1pbiJdfSwicmVzb3VyY2VfYWNjZXNzIjp7ImFjY291bnQiOnsicm9sZXMiOlsibWFuYWdlLWFjY291bnQiLCJtYW5hZ2UtYWNjb3VudC1saW5rcyIsInZpZXctcHJvZmlsZSJdfX0sInNjb3BlIjoiZW1haWwgcHJvZmlsZSIsImVtYWlsX3ZlcmlmaWVkIjp0cnVlLCJwcmVmZXJyZWRfdXNlcm5hbWUiOiJ1c2VyIn0.nwbrJkWdCNjzFrTDwKNuV5h9dDMg5ytRKGOXmFIajpfsbOutJytjWTCB2WpA8E1YI3KM6gU6Jx7cd7u0oPo5syHhfCz119n_wBiDnyTZkFOAPsx0M2z20kvBLN9k36_VfuCMFUeddJjO31MeLTmxB0UKg2VkxdczmzMH3pnalhxqpnWWk3GnrRrhAf2sZog0foH4Ae3Ks0lYtYzaWK_Yo7E4Px42-gJpohy3JevOC44aJ4auzJR1RBj9LUbgcRinkBy0JLi6XXiYznSC2V485CSBHW3sseXn7pSXQADhnmGQrLfFGO5ZljmPO18eFJaimdjvgSChsrlSEmTDDsoo5Q","expires_in":300,"refresh_expires_in":1800,"refresh_token":"eyJhbGciOiJIUzI1NiIsInR5cCIgOiAiSldUIiwia2lkIiA6ICJhMzZlMGU0NC02MWNmLTQ5NmMtOGRlZi03NTkwNjQ5MzQzMjEifQ.eyJleHAiOjE1OTAzOTk1NzEsImlhdCI6MTU5MDM5Nzc3MSwianRpIjoiNmMxNTBiY2EtYmE5NC00NTgxLWEwODEtYjI2YzhhMmI5YmZmIiwiaXNzIjoiaHR0cDovL2F1dGguZGVtby5wcmFnbWF0aWNpbmR1c3RyaWVzLmRlL2F1dGgvcmVhbG1zL0lvVERCIiwiYXVkIjoiaHR0cDovL2F1dGguZGVtby5wcmFnbWF0aWNpbmR1c3RyaWVzLmRlL2F1dGgvcmVhbG1zL0lvVERCIiwic3ViIjoiYmEzMmU0NzEtYzc3Mi00YjMzLThkYTYtNmZlOGFjZGEwMDczIiwidHlwIjoiUmVmcmVzaCIsImF6cCI6ImlvdGRiIiwic2Vzc2lvbl9zdGF0ZSI6IjA2MGQyODYyLTE0ZWQtNDJmZS1iYWY3LThkMWY3ODQ2NTdmMSIsInNjb3BlIjoiZW1haWwgcHJvZmlsZSJ9.ayNpXdNX28qahodX1zowrMGiUCw2AodlHBQFqr8Ui7c","token_type":"bearer","not-before-policy":0,"session_state":"060d2862-14ed-42fe-baf7-8d1f784657f1","scope":"email profile"} -``` - -### Cli 的批量操作 -当您想要通过脚本的方式通过 Cli / Shell 对 IoTDB 进行批量操作时，可以使用-e 参数。通过使用该参数，您可以在不进入客户端输入模式的情况下操作 IoTDB。 - -为了避免 SQL 语句和其他参数混淆，现在只支持-e 参数作为最后的参数使用。 - -针对 cli/Shell 工具的-e 参数用法如下： - -Linux 系统与 MacOS 指令： - -```shell -Shell > bash sbin/start-cli.sh -h {host} -p {rpcPort} -u {user} -pw {password} -e {sql for iotdb} -``` - -Windows 系统指令 -```shell -Shell > sbin\start-cli.bat -h {host} -p {rpcPort} -u {user} -pw {password} -e {sql for iotdb} -``` - -在 Windows 环境下，-e 参数的 SQL 语句需要使用` `` `对于`" "`进行替换 - -为了更好的解释-e 参数的使用，可以参考下面在 Linux 上执行的例子。 - -假设用户希望对一个新启动的 IoTDB 进行如下操作： - -1. 创建名为 root.demo 的 database - -2. 创建名为 root.demo.s1 的时间序列 - -3. 向创建的时间序列中插入三个数据点 - -4. 查询验证数据是否插入成功 - -那么通过使用 cli/Shell 工具的 -e 参数，可以采用如下的脚本： - -```shell -# !/bin/bash - -host=127.0.0.1 -rpcPort=6667 -user=root -pass=root - -bash ./sbin/start-cli.sh -h ${host} -p ${rpcPort} -u ${user} -pw ${pass} -e "CREATE DATABASE root.demo" -bash ./sbin/start-cli.sh -h ${host} -p ${rpcPort} -u ${user} -pw ${pass} -e "create timeseries root.demo.s1 WITH DATATYPE=INT32, ENCODING=RLE" -bash ./sbin/start-cli.sh -h ${host} -p ${rpcPort} -u ${user} -pw ${pass} -e "insert into root.demo(timestamp,s1) values(1,10)" -bash ./sbin/start-cli.sh -h ${host} -p ${rpcPort} -u ${user} -pw ${pass} -e "insert into root.demo(timestamp,s1) values(2,11)" -bash ./sbin/start-cli.sh -h ${host} -p ${rpcPort} -u ${user} -pw ${pass} -e "insert into root.demo(timestamp,s1) values(3,12)" -bash ./sbin/start-cli.sh -h ${host} -p ${rpcPort} -u ${user} -pw ${pass} -e "select s1 from root.demo" -``` - -打印出来的结果显示如下，通过这种方式进行的操作与客户端的输入模式以及通过 JDBC 进行操作结果是一致的。 - -```shell - Shell > bash ./shell.sh -+-----------------------------+------------+ -| Time|root.demo.s1| -+-----------------------------+------------+ -|1970-01-01T08:00:00.001+08:00| 10| -|1970-01-01T08:00:00.002+08:00| 11| -|1970-01-01T08:00:00.003+08:00| 12| -+-----------------------------+------------+ -Total line number = 3 -It costs 0.267s -``` - -需要特别注意的是，在脚本中使用 -e 参数时要对特殊字符进行转义。 - +--> \ No newline at end of file diff --git a/src/zh/UserGuide/V1.3.x/Tools-System/CLI_apache.md b/src/zh/UserGuide/V1.3.x/Tools-System/CLI_apache.md new file mode 100644 index 000000000..4e7125f51 --- /dev/null +++ b/src/zh/UserGuide/V1.3.x/Tools-System/CLI_apache.md @@ -0,0 +1,276 @@ + + +# SQL 命令行终端 (CLI) + +IOTDB 为用户提供 cli/Shell 工具用于启动客户端和服务端程序。下面介绍每个 cli/Shell 工具的运行方式和相关参数。 +> \$IOTDB\_HOME 表示 IoTDB 的安装目录所在路径。 + +## 安装 +如果使用源码版，可以在 iotdb 的根目录下执行 + +```shell +> mvn clean package -pl cli -am -DskipTests +``` + +在生成完毕之后，IoTDB 的 Cli 工具位于文件夹"cli/target/iotdb-cli-{project.version}"中。 + +如果你下载的是二进制版，那么 Cli 可以在 sbin 文件夹下直接找到。 + +## 运行 + +### Cli 运行方式 +安装后的 IoTDB 中有一个默认用户：`root`，默认密码为`root`。用户可以使用该用户尝试运行 IoTDB 客户端以测试服务器是否正常启动。客户端启动脚本为$IOTDB_HOME/sbin 文件夹下的`start-cli`脚本。启动脚本时需要指定运行 IP 和 RPC PORT。以下为服务器在本机启动，且用户未更改运行端口号的示例，默认端口为 6667。若用户尝试连接远程服务器或更改了服务器运行的端口号，请在-h 和-p 项处使用服务器的 IP 和 RPC PORT。
+用户也可以在启动脚本的最前方设置自己的环境变量，如 JAVA_HOME 等 （对于 linux 用户，脚本路径为："/sbin/start-cli.sh"； 对于 windows 用户，脚本路径为："/sbin/start-cli.bat") + +Linux 系统与 MacOS 系统启动命令如下： + +```shell +Shell > bash sbin/start-cli.sh -h 127.0.0.1 -p 6667 -u root -pw root +``` +Windows 系统启动命令如下： + +```shell +Shell > sbin\start-cli.bat -h 127.0.0.1 -p 6667 -u root -pw root +``` +回车后即可成功启动客户端。启动后出现如图提示即为启动成功。 + +``` + _____ _________ ______ ______ +|_ _| | _ _ ||_ _ `.|_ _ \ + | | .--.|_/ | | \_| | | `. \ | |_) | + | | / .'`\ \ | | | | | | | __'. + _| |_| \__. | _| |_ _| |_.' /_| |__) | +|_____|'.__.' |_____| |______.'|_______/ version + +Successfully login at 127.0.0.1:6667 +``` +输入`quit`或`exit`可退出 cli 结束本次会话，cli 输出`quit normally`表示退出成功。 + +### Cli 运行参数 + +|参数名|参数类型|是否为必需参数| 说明| 例子 | +|:---|:---|:---|:---|:---| +|-disableISO8601 |没有参数 | 否 |如果设置了这个参数，IoTDB 将以数字的形式打印时间戳 (timestamp)。|-disableISO8601| +|-h <`host`> |string 类型，不需要引号|是|IoTDB 客户端连接 IoTDB 服务器的 IP 地址。|-h 10.129.187.21| +|-help|没有参数|否|打印 IoTDB 的帮助信息|-help| +|-p <`rpcPort`>|int 类型|是|IoTDB 连接服务器的端口号，IoTDB 默认运行在 6667 端口。|-p 6667| +|-pw <`password`>|string 类型，不需要引号|否|IoTDB 连接服务器所使用的密码。如果没有输入密码 IoTDB 会在 Cli 端提示输入密码。|-pw root| +|-u <`username`>|string 类型，不需要引号|是|IoTDB 连接服务器锁使用的用户名。|-u root| +|-maxPRC <`maxPrintRowCount`>|int 类型|否|设置 IoTDB 返回客户端命令行中所显示的最大行数。|-maxPRC 10| +|-e <`execute`> |string 类型|否|在不进入客户端输入模式的情况下，批量操作 IoTDB|-e "show databases"| +|-c | 空 | 否 | 如果服务器设置了 `rpc_thrift_compression_enable=true`, 则 CLI 必须使用 `-c` | -c | + +下面展示一条客户端命令，功能是连接 IP 为 10.129.187.21 的主机，端口为 6667 ，用户名为 root，密码为 root，以数字的形式打印时间戳，IoTDB 命令行显示的最大行数为 10。 + +Linux 系统与 MacOS 系统启动命令如下： + +```shell +Shell > bash sbin/start-cli.sh -h 10.129.187.21 -p 6667 -u root -pw root -disableISO8601 -maxPRC 10 +``` +Windows 系统启动命令如下： + +```shell +Shell > sbin\start-cli.bat -h 10.129.187.21 -p 6667 -u root -pw root -disableISO8601 -maxPRC 10 +``` + +### CLI 特殊命令 +下面列举了一些CLI的特殊命令。 + +| 命令 | 描述 / 例子 | +|:---|:---| +| `set time_display_type=xxx` | 例如： long, default, ISO8601, yyyy-MM-dd HH:mm:ss | +| `show time_display_type` | 显示时间显示方式 | +| `set time_zone=xxx` | 例如： +08:00, Asia/Shanghai | +| `show time_zone` | 显示CLI的时区 | +| `set fetch_size=xxx` | 设置从服务器查询数据时的读取条数 | +| `show fetch_size` | 显示读取条数的大小 | +| `set max_display_num=xxx` | 设置 CLI 一次展示的最大数据条数， 设置为-1表示无限制 | +| `help` | 获取CLI特殊命令的提示 | +| `exit/quit` | 退出CLI | + +### 使用 OpenID 作为用户名认证登录 + +OpenID Connect (OIDC) 使用 keycloack 作为 OIDC 服务权限认证服务。 + +#### 配置 +配置位于 iotdb-system.properties，设定 authorizer_provider_class 为 org.apache.iotdb.commons.auth.authorizer.OpenIdAuthorizer 则开启了 openID 服务，默认情况下值为 org.apache.iotdb.commons.auth.authorizer.LocalFileAuthorizer 表示没有开启 openID 服务。 + +``` +authorizer_provider_class=org.apache.iotdb.commons.auth.authorizer.OpenIdAuthorizer +``` +如果开启了 openID 服务则 openID_url 为必填项，openID_url 值为 http://ip:port/realms/{realmsName} + +``` +openID_url=http://127.0.0.1:8080/realms/iotdb/ +``` +#### keycloack 配置 + +1、下载 keycloack 程序（此教程为21.1.0版本），在 keycloack/bin 中启动 keycloack + +```shell +Shell > cd bin +Shell > ./kc.sh start-dev +``` +2、使用 https://ip:port 登陆 keycloack, 首次登陆需要创建用户 + +![avatar](/img/UserGuide/CLI/Command-Line-Interface/login_keycloak.png?raw=true) + +3、点击 Administration Console 进入管理端 + +![avatar](/img/UserGuide/CLI/Command-Line-Interface/AdministrationConsole.png?raw=true) + +4、在左侧的 Master 菜单点击 Create Realm, 输入 Realm Name 创建一个新的 Realm + +![avatar](/img/UserGuide/CLI/Command-Line-Interface/add_Realm_1.jpg?raw=true) + +![avatar](/img/UserGuide/CLI/Command-Line-Interface/add_Realm_2.jpg?raw=true) + +5、点击左侧菜单 Clients，创建 client + +![avatar](/img/UserGuide/CLI/Command-Line-Interface/client.jpg?raw=true) + +6、点击左侧菜单 User，创建 user + +![avatar](/img/UserGuide/CLI/Command-Line-Interface/user.jpg?raw=true) + +7、点击新创建的用户 id，点击 Credentials 导航输入密码和关闭 Temporary 选项，至此 keyclork 配置完成 + +![avatar](/img/UserGuide/CLI/Command-Line-Interface/pwd.jpg?raw=true) + +8、创建角色，点击左侧菜单的 Roles然后点击Create Role 按钮添加角色 + +![avatar](/img/UserGuide/CLI/Command-Line-Interface/add_role1.jpg?raw=true) + +9、在Role Name 中输入`iotdb_admin`，点击save 按钮。提示：这里的`iotdb_admin`不能为其他名称否则即使登陆成功后也将无权限使用iotdb的查询、插入、创建 database、添加用户、角色等功能 + +![avatar](/img/UserGuide/CLI/Command-Line-Interface/add_role2.jpg?raw=true) + +10、点击左侧的User 菜单然后点击用户列表中的用户为该用户添加我们刚创建的`iotdb_admin`角色 + +![avatar](/img/UserGuide/CLI/Command-Line-Interface/add_role3.jpg?raw=true) + +11、选择Role Mappings ，在Assign role选择`iotdb_admin`增加角色 + +![avatar](/img/UserGuide/CLI/Command-Line-Interface/add_role4.jpg?raw=true) + +![avatar](/img/UserGuide/CLI/Command-Line-Interface/add_role5.jpg?raw=true) + +提示：如果用户角色有调整需要重新生成token并且重新登陆iotdb才会生效 + +以上步骤提供了一种 keycloak 登陆 iotdb 方式，更多方式请参考 keycloak 配置 + +若对应的 IoTDB 服务器开启了使用 OpenID Connect (OIDC) 作为权限认证服务，那么就不再需要使用用户名密码进行登录。 +替而代之的是使用 Token，以及空密码。 +此时，登录命令如下： + +```shell +Shell > bash sbin/start-cli.sh -h 10.129.187.21 -p 6667 -u {my-access-token} -pw "" +``` + +其中，需要将{my-access-token} （注意，包括{}）替换成你的 token，即 access_token 对应的值。密码为空需要再次确认。 + +![avatar](/img/UserGuide/CLI/Command-Line-Interface/iotdbpw.jpeg?raw=true) + +如何获取 token 取决于你的 OIDC 设置。 最简单的一种情况是使用`password-grant`。例如，假设你在用 keycloack 作为你的 OIDC 服务， +并且你在 keycloack 中有一个被定义成 public 的`iotdb`客户的 realm，那么你可以使用如下`curl`命令获得 token。 +（注意例子中的{}和里面的内容需要替换成具体的服务器地址和 realm 名字）： +```shell +curl -X POST "http://{your-keycloack-server}/realms/{your-realm}/protocol/openid-connect/token" \ -H "Content-Type: application/x-www-form-urlencoded" \ + -d "username={username}" \ + -d "password={password}" \ + -d 'grant_type=password' \ + -d "client_id=iotdb-client" +``` + +示例结果如下： + +```json +{"access_token":"eyJhbGciOiJSUzI1NiIsInR5cCIgOiAiSldUIiwia2lkIiA6ICJxMS1XbTBvelE1TzBtUUg4LVNKYXAyWmNONE1tdWNXd25RV0tZeFpKNG93In0.eyJleHAiOjE1OTAzOTgwNzEsImlhdCI6MTU5MDM5Nzc3MSwianRpIjoiNjA0ZmYxMDctN2NiNy00NTRmLWIwYmQtY2M2ZDQwMjFiNGU4IiwiaXNzIjoiaHR0cDovL2F1dGguZGVtby5wcmFnbWF0aWNpbmR1c3RyaWVzLmRlL2F1dGgvcmVhbG1zL0lvVERCIiwiYXVkIjoiYWNjb3VudCIsInN1YiI6ImJhMzJlNDcxLWM3NzItNGIzMy04ZGE2LTZmZThhY2RhMDA3MyIsInR5cCI6IkJlYXJlciIsImF6cCI6ImlvdGRiIiwic2Vzc2lvbl9zdGF0ZSI6IjA2MGQyODYyLTE0ZWQtNDJmZS1iYWY3LThkMWY3ODQ2NTdmMSIsImFjciI6IjEiLCJhbGxvd2VkLW9yaWdpbnMiOlsibG9jYWxob3N0OjgwODAiXSwicmVhbG1fYWNjZXNzIjp7InJvbGVzIjpbIm9mZmxpbmVfYWNjZXNzIiwidW1hX2F1dGhvcml6YXRpb24iLCJpb3RkYl9hZG1pbiJdfSwicmVzb3VyY2VfYWNjZXNzIjp7ImFjY291bnQiOnsicm9sZXMiOlsibWFuYWdlLWFjY291bnQiLCJtYW5hZ2UtYWNjb3VudC1saW5rcyIsInZpZXctcHJvZmlsZSJdfX0sInNjb3BlIjoiZW1haWwgcHJvZmlsZSIsImVtYWlsX3ZlcmlmaWVkIjp0cnVlLCJwcmVmZXJyZWRfdXNlcm5hbWUiOiJ1c2VyIn0.nwbrJkWdCNjzFrTDwKNuV5h9dDMg5ytRKGOXmFIajpfsbOutJytjWTCB2WpA8E1YI3KM6gU6Jx7cd7u0oPo5syHhfCz119n_wBiDnyTZkFOAPsx0M2z20kvBLN9k36_VfuCMFUeddJjO31MeLTmxB0UKg2VkxdczmzMH3pnalhxqpnWWk3GnrRrhAf2sZog0foH4Ae3Ks0lYtYzaWK_Yo7E4Px42-gJpohy3JevOC44aJ4auzJR1RBj9LUbgcRinkBy0JLi6XXiYznSC2V485CSBHW3sseXn7pSXQADhnmGQrLfFGO5ZljmPO18eFJaimdjvgSChsrlSEmTDDsoo5Q","expires_in":300,"refresh_expires_in":1800,"refresh_token":"eyJhbGciOiJIUzI1NiIsInR5cCIgOiAiSldUIiwia2lkIiA6ICJhMzZlMGU0NC02MWNmLTQ5NmMtOGRlZi03NTkwNjQ5MzQzMjEifQ.eyJleHAiOjE1OTAzOTk1NzEsImlhdCI6MTU5MDM5Nzc3MSwianRpIjoiNmMxNTBiY2EtYmE5NC00NTgxLWEwODEtYjI2YzhhMmI5YmZmIiwiaXNzIjoiaHR0cDovL2F1dGguZGVtby5wcmFnbWF0aWNpbmR1c3RyaWVzLmRlL2F1dGgvcmVhbG1zL0lvVERCIiwiYXVkIjoiaHR0cDovL2F1dGguZGVtby5wcmFnbWF0aWNpbmR1c3RyaWVzLmRlL2F1dGgvcmVhbG1zL0lvVERCIiwic3ViIjoiYmEzMmU0NzEtYzc3Mi00YjMzLThkYTYtNmZlOGFjZGEwMDczIiwidHlwIjoiUmVmcmVzaCIsImF6cCI6ImlvdGRiIiwic2Vzc2lvbl9zdGF0ZSI6IjA2MGQyODYyLTE0ZWQtNDJmZS1iYWY3LThkMWY3ODQ2NTdmMSIsInNjb3BlIjoiZW1haWwgcHJvZmlsZSJ9.ayNpXdNX28qahodX1zowrMGiUCw2AodlHBQFqr8Ui7c","token_type":"bearer","not-before-policy":0,"session_state":"060d2862-14ed-42fe-baf7-8d1f784657f1","scope":"email profile"} +``` + +### Cli 的批量操作 +当您想要通过脚本的方式通过 Cli / Shell 对 IoTDB 进行批量操作时，可以使用-e 参数。通过使用该参数，您可以在不进入客户端输入模式的情况下操作 IoTDB。 + +为了避免 SQL 语句和其他参数混淆，现在只支持-e 参数作为最后的参数使用。 + +针对 cli/Shell 工具的-e 参数用法如下： + +Linux 系统与 MacOS 指令： + +```shell +Shell > bash sbin/start-cli.sh -h {host} -p {rpcPort} -u {user} -pw {password} -e {sql for iotdb} +``` + +Windows 系统指令 +```shell +Shell > sbin\start-cli.bat -h {host} -p {rpcPort} -u {user} -pw {password} -e {sql for iotdb} +``` + +在 Windows 环境下，-e 参数的 SQL 语句需要使用` `` `对于`" "`进行替换 + +为了更好的解释-e 参数的使用，可以参考下面在 Linux 上执行的例子。 + +假设用户希望对一个新启动的 IoTDB 进行如下操作： + +1. 创建名为 root.demo 的 database + +2. 创建名为 root.demo.s1 的时间序列 + +3. 向创建的时间序列中插入三个数据点 + +4. 查询验证数据是否插入成功 + +那么通过使用 cli/Shell 工具的 -e 参数，可以采用如下的脚本： + +```shell +# !/bin/bash + +host=127.0.0.1 +rpcPort=6667 +user=root +pass=root + +bash ./sbin/start-cli.sh -h ${host} -p ${rpcPort} -u ${user} -pw ${pass} -e "CREATE DATABASE root.demo" +bash ./sbin/start-cli.sh -h ${host} -p ${rpcPort} -u ${user} -pw ${pass} -e "create timeseries root.demo.s1 WITH DATATYPE=INT32, ENCODING=RLE" +bash ./sbin/start-cli.sh -h ${host} -p ${rpcPort} -u ${user} -pw ${pass} -e "insert into root.demo(timestamp,s1) values(1,10)" +bash ./sbin/start-cli.sh -h ${host} -p ${rpcPort} -u ${user} -pw ${pass} -e "insert into root.demo(timestamp,s1) values(2,11)" +bash ./sbin/start-cli.sh -h ${host} -p ${rpcPort} -u ${user} -pw ${pass} -e "insert into root.demo(timestamp,s1) values(3,12)" +bash ./sbin/start-cli.sh -h ${host} -p ${rpcPort} -u ${user} -pw ${pass} -e "select s1 from root.demo" +``` + +打印出来的结果显示如下，通过这种方式进行的操作与客户端的输入模式以及通过 JDBC 进行操作结果是一致的。 + +```shell + Shell > bash ./shell.sh ++-----------------------------+------------+ +| Time|root.demo.s1| ++-----------------------------+------------+ +|1970-01-01T08:00:00.001+08:00| 10| +|1970-01-01T08:00:00.002+08:00| 11| +|1970-01-01T08:00:00.003+08:00| 12| ++-----------------------------+------------+ +Total line number = 3 +It costs 0.267s +``` + +需要特别注意的是，在脚本中使用 -e 参数时要对特殊字符进行转义。 + diff --git a/src/zh/UserGuide/V1.3.x/Tools-System/CLI_timecho.md b/src/zh/UserGuide/V1.3.x/Tools-System/CLI_timecho.md new file mode 100644 index 000000000..e8fc508bd --- /dev/null +++ b/src/zh/UserGuide/V1.3.x/Tools-System/CLI_timecho.md @@ -0,0 +1,263 @@ + + +# SQL 命令行终端 (CLI) + +IOTDB 为用户提供 cli/Shell 工具用于启动客户端和服务端程序。下面介绍每个 cli/Shell 工具的运行方式和相关参数。 +> \$IOTDB\_HOME 表示 IoTDB 的安装目录所在路径。 + +## Cli 运行方式 +安装后的 IoTDB 中有一个默认用户：`root`，默认密码为`root`。用户可以使用该用户尝试运行 IoTDB 客户端以测试服务器是否正常启动。客户端启动脚本为$IOTDB_HOME/sbin 文件夹下的`start-cli`脚本。启动脚本时需要指定运行 IP 和 RPC PORT。以下为服务器在本机启动，且用户未更改运行端口号的示例，默认端口为 6667。若用户尝试连接远程服务器或更改了服务器运行的端口号，请在-h 和-p 项处使用服务器的 IP 和 RPC PORT。
+用户也可以在启动脚本的最前方设置自己的环境变量，如 JAVA_HOME 等 （对于 linux 用户，脚本路径为："/sbin/start-cli.sh"； 对于 windows 用户，脚本路径为："/sbin/start-cli.bat") + +Linux 系统与 MacOS 系统启动命令如下： + +```shell +Shell > bash sbin/start-cli.sh -h 127.0.0.1 -p 6667 -u root -pw root +``` +Windows 系统启动命令如下： + +```shell +Shell > sbin\start-cli.bat -h 127.0.0.1 -p 6667 -u root -pw root +``` +回车后即可成功启动客户端。启动后出现如图提示即为启动成功。 + +``` + _____ _________ ______ ______ +|_ _| | _ _ ||_ _ `.|_ _ \ + | | .--.|_/ | | \_| | | `. \ | |_) | + | | / .'`\ \ | | | | | | | __'. + _| |_| \__. | _| |_ _| |_.' /_| |__) | +|_____|'.__.' |_____| |______.'|_______/ version + +Successfully login at 127.0.0.1:6667 +``` +输入`quit`或`exit`可退出 cli 结束本次会话，cli 输出`quit normally`表示退出成功。 + +## Cli 运行参数 + +|参数名|参数类型|是否为必需参数| 说明| 例子 | +|:---|:---|:---|:---|:---| +|-disableISO8601 |没有参数 | 否 |如果设置了这个参数，IoTDB 将以数字的形式打印时间戳 (timestamp)。|-disableISO8601| +|-h <`host`> |string 类型，不需要引号|是|IoTDB 客户端连接 IoTDB 服务器的 IP 地址。|-h 10.129.187.21| +|-help|没有参数|否|打印 IoTDB 的帮助信息|-help| +|-p <`rpcPort`>|int 类型|是|IoTDB 连接服务器的端口号，IoTDB 默认运行在 6667 端口。|-p 6667| +|-pw <`password`>|string 类型，不需要引号|否|IoTDB 连接服务器所使用的密码。如果没有输入密码 IoTDB 会在 Cli 端提示输入密码。|-pw root| +|-u <`username`>|string 类型，不需要引号|是|IoTDB 连接服务器锁使用的用户名。|-u root| +|-maxPRC <`maxPrintRowCount`>|int 类型|否|设置 IoTDB 返回客户端命令行中所显示的最大行数。|-maxPRC 10| +|-e <`execute`> |string 类型|否|在不进入客户端输入模式的情况下，批量操作 IoTDB|-e "show databases"| +|-c | 空 | 否 | 如果服务器设置了 `rpc_thrift_compression_enable=true`, 则 CLI 必须使用 `-c` | -c | + +下面展示一条客户端命令，功能是连接 IP 为 10.129.187.21 的主机，端口为 6667 ，用户名为 root，密码为 root，以数字的形式打印时间戳，IoTDB 命令行显示的最大行数为 10。 + +Linux 系统与 MacOS 系统启动命令如下： + +```shell +Shell > bash sbin/start-cli.sh -h 10.129.187.21 -p 6667 -u root -pw root -disableISO8601 -maxPRC 10 +``` +Windows 系统启动命令如下： + +```shell +Shell > sbin\start-cli.bat -h 10.129.187.21 -p 6667 -u root -pw root -disableISO8601 -maxPRC 10 +``` + +## CLI 特殊命令 +下面列举了一些CLI的特殊命令。 + +| 命令 | 描述 / 例子 | +|:---|:---| +| `set time_display_type=xxx` | 例如： long, default, ISO8601, yyyy-MM-dd HH:mm:ss | +| `show time_display_type` | 显示时间显示方式 | +| `set time_zone=xxx` | 例如： +08:00, Asia/Shanghai | +| `show time_zone` | 显示CLI的时区 | +| `set fetch_size=xxx` | 设置从服务器查询数据时的读取条数 | +| `show fetch_size` | 显示读取条数的大小 | +| `set max_display_num=xxx` | 设置 CLI 一次展示的最大数据条数， 设置为-1表示无限制 | +| `help` | 获取CLI特殊命令的提示 | +| `exit/quit` | 退出CLI | + +## 使用 OpenID 作为用户名认证登录 + +OpenID Connect (OIDC) 使用 keycloack 作为 OIDC 服务权限认证服务。 + +### 配置 +配置位于 iotdb-system.properties，设定 authorizer_provider_class 为 org.apache.iotdb.commons.auth.authorizer.OpenIdAuthorizer 则开启了 openID 服务，默认情况下值为 org.apache.iotdb.commons.auth.authorizer.LocalFileAuthorizer 表示没有开启 openID 服务。 + +``` +authorizer_provider_class=org.apache.iotdb.commons.auth.authorizer.OpenIdAuthorizer +``` +如果开启了 openID 服务则 openID_url 为必填项，openID_url 值为 http://ip:port/realms/{realmsName} + +``` +openID_url=http://127.0.0.1:8080/realms/iotdb/ +``` +### keycloack 配置 + +1、下载 keycloack 程序（此教程为21.1.0版本），在 keycloack/bin 中启动 keycloack + +```shell +Shell > cd bin +Shell > ./kc.sh start-dev +``` +2、使用 https://ip:port 登陆 keycloack, 首次登陆需要创建用户 + +![avatar](/img/UserGuide/CLI/Command-Line-Interface/login_keycloak.png?raw=true) + +3、点击 Administration Console 进入管理端 + +![avatar](/img/UserGuide/CLI/Command-Line-Interface/AdministrationConsole.png?raw=true) + +4、在左侧的 Master 菜单点击 Create Realm, 输入 Realm Name 创建一个新的 Realm + +![avatar](/img/UserGuide/CLI/Command-Line-Interface/add_Realm_1.jpg?raw=true) + +![avatar](/img/UserGuide/CLI/Command-Line-Interface/add_Realm_2.jpg?raw=true) + +5、点击左侧菜单 Clients，创建 client + +![avatar](/img/UserGuide/CLI/Command-Line-Interface/client.jpg?raw=true) + +6、点击左侧菜单 User，创建 user + +![avatar](/img/UserGuide/CLI/Command-Line-Interface/user.jpg?raw=true) + +7、点击新创建的用户 id，点击 Credentials 导航输入密码和关闭 Temporary 选项，至此 keyclork 配置完成 + +![avatar](/img/UserGuide/CLI/Command-Line-Interface/pwd.jpg?raw=true) + +8、创建角色，点击左侧菜单的 Roles然后点击Create Role 按钮添加角色 + +![avatar](/img/UserGuide/CLI/Command-Line-Interface/add_role1.jpg?raw=true) + +9、在Role Name 中输入`iotdb_admin`，点击save 按钮。提示：这里的`iotdb_admin`不能为其他名称否则即使登陆成功后也将无权限使用iotdb的查询、插入、创建 database、添加用户、角色等功能 + +![avatar](/img/UserGuide/CLI/Command-Line-Interface/add_role2.jpg?raw=true) + +10、点击左侧的User 菜单然后点击用户列表中的用户为该用户添加我们刚创建的`iotdb_admin`角色 + +![avatar](/img/UserGuide/CLI/Command-Line-Interface/add_role3.jpg?raw=true) + +11、选择Role Mappings ，在Assign role选择`iotdb_admin`增加角色 + +![avatar](/img/UserGuide/CLI/Command-Line-Interface/add_role4.jpg?raw=true) + +![avatar](/img/UserGuide/CLI/Command-Line-Interface/add_role5.jpg?raw=true) + +提示：如果用户角色有调整需要重新生成token并且重新登陆iotdb才会生效 + +以上步骤提供了一种 keycloak 登陆 iotdb 方式，更多方式请参考 keycloak 配置 + +若对应的 IoTDB 服务器开启了使用 OpenID Connect (OIDC) 作为权限认证服务，那么就不再需要使用用户名密码进行登录。 +替而代之的是使用 Token，以及空密码。 +此时，登录命令如下： + +```shell +Shell > bash sbin/start-cli.sh -h 10.129.187.21 -p 6667 -u {my-access-token} -pw "" +``` + +其中，需要将{my-access-token} （注意，包括{}）替换成你的 token，即 access_token 对应的值。密码为空需要再次确认。 + +![avatar](/img/UserGuide/CLI/Command-Line-Interface/iotdbpw.jpeg?raw=true) + +如何获取 token 取决于你的 OIDC 设置。 最简单的一种情况是使用`password-grant`。例如，假设你在用 keycloack 作为你的 OIDC 服务， +并且你在 keycloack 中有一个被定义成 public 的`iotdb`客户的 realm，那么你可以使用如下`curl`命令获得 token。 +（注意例子中的{}和里面的内容需要替换成具体的服务器地址和 realm 名字）： +```shell +curl -X POST "http://{your-keycloack-server}/realms/{your-realm}/protocol/openid-connect/token" \ -H "Content-Type: application/x-www-form-urlencoded" \ + -d "username={username}" \ + -d "password={password}" \ + -d 'grant_type=password' \ + -d "client_id=iotdb-client" +``` + +示例结果如下： + +```json +{"access_token":"eyJhbGciOiJSUzI1NiIsInR5cCIgOiAiSldUIiwia2lkIiA6ICJxMS1XbTBvelE1TzBtUUg4LVNKYXAyWmNONE1tdWNXd25RV0tZeFpKNG93In0.eyJleHAiOjE1OTAzOTgwNzEsImlhdCI6MTU5MDM5Nzc3MSwianRpIjoiNjA0ZmYxMDctN2NiNy00NTRmLWIwYmQtY2M2ZDQwMjFiNGU4IiwiaXNzIjoiaHR0cDovL2F1dGguZGVtby5wcmFnbWF0aWNpbmR1c3RyaWVzLmRlL2F1dGgvcmVhbG1zL0lvVERCIiwiYXVkIjoiYWNjb3VudCIsInN1YiI6ImJhMzJlNDcxLWM3NzItNGIzMy04ZGE2LTZmZThhY2RhMDA3MyIsInR5cCI6IkJlYXJlciIsImF6cCI6ImlvdGRiIiwic2Vzc2lvbl9zdGF0ZSI6IjA2MGQyODYyLTE0ZWQtNDJmZS1iYWY3LThkMWY3ODQ2NTdmMSIsImFjciI6IjEiLCJhbGxvd2VkLW9yaWdpbnMiOlsibG9jYWxob3N0OjgwODAiXSwicmVhbG1fYWNjZXNzIjp7InJvbGVzIjpbIm9mZmxpbmVfYWNjZXNzIiwidW1hX2F1dGhvcml6YXRpb24iLCJpb3RkYl9hZG1pbiJdfSwicmVzb3VyY2VfYWNjZXNzIjp7ImFjY291bnQiOnsicm9sZXMiOlsibWFuYWdlLWFjY291bnQiLCJtYW5hZ2UtYWNjb3VudC1saW5rcyIsInZpZXctcHJvZmlsZSJdfX0sInNjb3BlIjoiZW1haWwgcHJvZmlsZSIsImVtYWlsX3ZlcmlmaWVkIjp0cnVlLCJwcmVmZXJyZWRfdXNlcm5hbWUiOiJ1c2VyIn0.nwbrJkWdCNjzFrTDwKNuV5h9dDMg5ytRKGOXmFIajpfsbOutJytjWTCB2WpA8E1YI3KM6gU6Jx7cd7u0oPo5syHhfCz119n_wBiDnyTZkFOAPsx0M2z20kvBLN9k36_VfuCMFUeddJjO31MeLTmxB0UKg2VkxdczmzMH3pnalhxqpnWWk3GnrRrhAf2sZog0foH4Ae3Ks0lYtYzaWK_Yo7E4Px42-gJpohy3JevOC44aJ4auzJR1RBj9LUbgcRinkBy0JLi6XXiYznSC2V485CSBHW3sseXn7pSXQADhnmGQrLfFGO5ZljmPO18eFJaimdjvgSChsrlSEmTDDsoo5Q","expires_in":300,"refresh_expires_in":1800,"refresh_token":"eyJhbGciOiJIUzI1NiIsInR5cCIgOiAiSldUIiwia2lkIiA6ICJhMzZlMGU0NC02MWNmLTQ5NmMtOGRlZi03NTkwNjQ5MzQzMjEifQ.eyJleHAiOjE1OTAzOTk1NzEsImlhdCI6MTU5MDM5Nzc3MSwianRpIjoiNmMxNTBiY2EtYmE5NC00NTgxLWEwODEtYjI2YzhhMmI5YmZmIiwiaXNzIjoiaHR0cDovL2F1dGguZGVtby5wcmFnbWF0aWNpbmR1c3RyaWVzLmRlL2F1dGgvcmVhbG1zL0lvVERCIiwiYXVkIjoiaHR0cDovL2F1dGguZGVtby5wcmFnbWF0aWNpbmR1c3RyaWVzLmRlL2F1dGgvcmVhbG1zL0lvVERCIiwic3ViIjoiYmEzMmU0NzEtYzc3Mi00YjMzLThkYTYtNmZlOGFjZGEwMDczIiwidHlwIjoiUmVmcmVzaCIsImF6cCI6ImlvdGRiIiwic2Vzc2lvbl9zdGF0ZSI6IjA2MGQyODYyLTE0ZWQtNDJmZS1iYWY3LThkMWY3ODQ2NTdmMSIsInNjb3BlIjoiZW1haWwgcHJvZmlsZSJ9.ayNpXdNX28qahodX1zowrMGiUCw2AodlHBQFqr8Ui7c","token_type":"bearer","not-before-policy":0,"session_state":"060d2862-14ed-42fe-baf7-8d1f784657f1","scope":"email profile"} +``` + +## Cli 的批量操作 +当您想要通过脚本的方式通过 Cli / Shell 对 IoTDB 进行批量操作时，可以使用-e 参数。通过使用该参数，您可以在不进入客户端输入模式的情况下操作 IoTDB。 + +为了避免 SQL 语句和其他参数混淆，现在只支持-e 参数作为最后的参数使用。 + +针对 cli/Shell 工具的-e 参数用法如下： + +Linux 系统与 MacOS 指令： + +```shell +Shell > bash sbin/start-cli.sh -h {host} -p {rpcPort} -u {user} -pw {password} -e {sql for iotdb} +``` + +Windows 系统指令 +```shell +Shell > sbin\start-cli.bat -h {host} -p {rpcPort} -u {user} -pw {password} -e {sql for iotdb} +``` + +在 Windows 环境下，-e 参数的 SQL 语句需要使用` `` `对于`" "`进行替换 + +为了更好的解释-e 参数的使用，可以参考下面在 Linux 上执行的例子。 + +假设用户希望对一个新启动的 IoTDB 进行如下操作： + +1. 创建名为 root.demo 的 database + +2. 创建名为 root.demo.s1 的时间序列 + +3. 向创建的时间序列中插入三个数据点 + +4. 查询验证数据是否插入成功 + +那么通过使用 cli/Shell 工具的 -e 参数，可以采用如下的脚本： + +```shell +# !/bin/bash + +host=127.0.0.1 +rpcPort=6667 +user=root +pass=root + +bash ./sbin/start-cli.sh -h ${host} -p ${rpcPort} -u ${user} -pw ${pass} -e "CREATE DATABASE root.demo" +bash ./sbin/start-cli.sh -h ${host} -p ${rpcPort} -u ${user} -pw ${pass} -e "create timeseries root.demo.s1 WITH DATATYPE=INT32, ENCODING=RLE" +bash ./sbin/start-cli.sh -h ${host} -p ${rpcPort} -u ${user} -pw ${pass} -e "insert into root.demo(timestamp,s1) values(1,10)" +bash ./sbin/start-cli.sh -h ${host} -p ${rpcPort} -u ${user} -pw ${pass} -e "insert into root.demo(timestamp,s1) values(2,11)" +bash ./sbin/start-cli.sh -h ${host} -p ${rpcPort} -u ${user} -pw ${pass} -e "insert into root.demo(timestamp,s1) values(3,12)" +bash ./sbin/start-cli.sh -h ${host} -p ${rpcPort} -u ${user} -pw ${pass} -e "select s1 from root.demo" +``` + +打印出来的结果显示如下，通过这种方式进行的操作与客户端的输入模式以及通过 JDBC 进行操作结果是一致的。 + +```shell + Shell > bash ./shell.sh ++-----------------------------+------------+ +| Time|root.demo.s1| ++-----------------------------+------------+ +|1970-01-01T08:00:00.001+08:00| 10| +|1970-01-01T08:00:00.002+08:00| 11| +|1970-01-01T08:00:00.003+08:00| 12| ++-----------------------------+------------+ +Total line number = 3 +It costs 0.267s +``` + +需要特别注意的是，在脚本中使用 -e 参数时要对特殊字符进行转义。 + diff --git a/src/zh/UserGuide/dev-1.3/Tools-System/CLI.md b/src/zh/UserGuide/dev-1.3/Tools-System/CLI.md index aaff80934..03580fafb 100644 --- a/src/zh/UserGuide/dev-1.3/Tools-System/CLI.md +++ b/src/zh/UserGuide/dev-1.3/Tools-System/CLI.md @@ -1,3 +1,6 @@ +--- +redirectTo: CLI_apache.html +--- - -# SQL 命令行终端 (CLI) - -IOTDB 为用户提供 cli/Shell 工具用于启动客户端和服务端程序。下面介绍每个 cli/Shell 工具的运行方式和相关参数。 -> \$IOTDB\_HOME 表示 IoTDB 的安装目录所在路径。 - -## 安装 -如果使用源码版，可以在 iotdb 的根目录下执行 - -```shell -> mvn clean package -pl cli -am -DskipTests -``` - -在生成完毕之后，IoTDB 的 Cli 工具位于文件夹"cli/target/iotdb-cli-{project.version}"中。 - -如果你下载的是二进制版，那么 Cli 可以在 sbin 文件夹下直接找到。 - -## 运行 - -### Cli 运行方式 -安装后的 IoTDB 中有一个默认用户：`root`，默认密码为`root`。用户可以使用该用户尝试运行 IoTDB 客户端以测试服务器是否正常启动。客户端启动脚本为$IOTDB_HOME/sbin 文件夹下的`start-cli`脚本。启动脚本时需要指定运行 IP 和 RPC PORT。以下为服务器在本机启动，且用户未更改运行端口号的示例，默认端口为 6667。若用户尝试连接远程服务器或更改了服务器运行的端口号，请在-h 和-p 项处使用服务器的 IP 和 RPC PORT。
-用户也可以在启动脚本的最前方设置自己的环境变量，如 JAVA_HOME 等 （对于 linux 用户，脚本路径为："/sbin/start-cli.sh"； 对于 windows 用户，脚本路径为："/sbin/start-cli.bat") - -Linux 系统与 MacOS 系统启动命令如下： - -```shell -Shell > bash sbin/start-cli.sh -h 127.0.0.1 -p 6667 -u root -pw root -``` -Windows 系统启动命令如下： - -```shell -Shell > sbin\start-cli.bat -h 127.0.0.1 -p 6667 -u root -pw root -``` -回车后即可成功启动客户端。启动后出现如图提示即为启动成功。 - -``` - _____ _________ ______ ______ -|_ _| | _ _ ||_ _ `.|_ _ \ - | | .--.|_/ | | \_| | | `. \ | |_) | - | | / .'`\ \ | | | | | | | __'. - _| |_| \__. | _| |_ _| |_.' /_| |__) | -|_____|'.__.' |_____| |______.'|_______/ version - -Successfully login at 127.0.0.1:6667 -``` -输入`quit`或`exit`可退出 cli 结束本次会话，cli 输出`quit normally`表示退出成功。 - -### Cli 运行参数 - -|参数名|参数类型|是否为必需参数| 说明| 例子 | -|:---|:---|:---|:---|:---| -|-disableISO8601 |没有参数 | 否 |如果设置了这个参数，IoTDB 将以数字的形式打印时间戳 (timestamp)。|-disableISO8601| -|-h <`host`> |string 类型，不需要引号|是|IoTDB 客户端连接 IoTDB 服务器的 IP 地址。|-h 10.129.187.21| -|-help|没有参数|否|打印 IoTDB 的帮助信息|-help| -|-p <`rpcPort`>|int 类型|是|IoTDB 连接服务器的端口号，IoTDB 默认运行在 6667 端口。|-p 6667| -|-pw <`password`>|string 类型，不需要引号|否|IoTDB 连接服务器所使用的密码。如果没有输入密码 IoTDB 会在 Cli 端提示输入密码。|-pw root| -|-u <`username`>|string 类型，不需要引号|是|IoTDB 连接服务器锁使用的用户名。|-u root| -|-maxPRC <`maxPrintRowCount`>|int 类型|否|设置 IoTDB 返回客户端命令行中所显示的最大行数。|-maxPRC 10| -|-e <`execute`> |string 类型|否|在不进入客户端输入模式的情况下，批量操作 IoTDB|-e "show databases"| -|-c | 空 | 否 | 如果服务器设置了 `rpc_thrift_compression_enable=true`, 则 CLI 必须使用 `-c` | -c | - -下面展示一条客户端命令，功能是连接 IP 为 10.129.187.21 的主机，端口为 6667 ，用户名为 root，密码为 root，以数字的形式打印时间戳，IoTDB 命令行显示的最大行数为 10。 - -Linux 系统与 MacOS 系统启动命令如下： - -```shell -Shell > bash sbin/start-cli.sh -h 10.129.187.21 -p 6667 -u root -pw root -disableISO8601 -maxPRC 10 -``` -Windows 系统启动命令如下： - -```shell -Shell > sbin\start-cli.bat -h 10.129.187.21 -p 6667 -u root -pw root -disableISO8601 -maxPRC 10 -``` - -### CLI 特殊命令 -下面列举了一些CLI的特殊命令。 - -| 命令 | 描述 / 例子 | -|:---|:---| -| `set time_display_type=xxx` | 例如： long, default, ISO8601, yyyy-MM-dd HH:mm:ss | -| `show time_display_type` | 显示时间显示方式 | -| `set time_zone=xxx` | 例如： +08:00, Asia/Shanghai | -| `show time_zone` | 显示CLI的时区 | -| `set fetch_size=xxx` | 设置从服务器查询数据时的读取条数 | -| `show fetch_size` | 显示读取条数的大小 | -| `set max_display_num=xxx` | 设置 CLI 一次展示的最大数据条数， 设置为-1表示无限制 | -| `help` | 获取CLI特殊命令的提示 | -| `exit/quit` | 退出CLI | - -### 使用 OpenID 作为用户名认证登录 - -OpenID Connect (OIDC) 使用 keycloack 作为 OIDC 服务权限认证服务。 - -#### 配置 -配置位于 iotdb-system.properties，设定 authorizer_provider_class 为 org.apache.iotdb.commons.auth.authorizer.OpenIdAuthorizer 则开启了 openID 服务，默认情况下值为 org.apache.iotdb.commons.auth.authorizer.LocalFileAuthorizer 表示没有开启 openID 服务。 - -``` -authorizer_provider_class=org.apache.iotdb.commons.auth.authorizer.OpenIdAuthorizer -``` -如果开启了 openID 服务则 openID_url 为必填项，openID_url 值为 http://ip:port/realms/{realmsName} - -``` -openID_url=http://127.0.0.1:8080/realms/iotdb/ -``` -####keycloack 配置 - -1、下载 keycloack 程序（此教程为21.1.0版本），在 keycloack/bin 中启动 keycloack - -```shell -Shell > cd bin -Shell > ./kc.sh start-dev -``` -2、使用 https://ip:port 登陆 keycloack, 首次登陆需要创建用户 - -![avatar](/img/UserGuide/CLI/Command-Line-Interface/login_keycloak.png?raw=true) - -3、点击 Administration Console 进入管理端 - -![avatar](/img/UserGuide/CLI/Command-Line-Interface/AdministrationConsole.png?raw=true) - -4、在左侧的 Master 菜单点击 Create Realm, 输入 Realm Name 创建一个新的 Realm - -![avatar](/img/UserGuide/CLI/Command-Line-Interface/add_Realm_1.jpg?raw=true) - -![avatar](/img/UserGuide/CLI/Command-Line-Interface/add_Realm_2.jpg?raw=true) - -5、点击左侧菜单 Clients，创建 client - -![avatar](/img/UserGuide/CLI/Command-Line-Interface/client.jpg?raw=true) - -6、点击左侧菜单 User，创建 user - -![avatar](/img/UserGuide/CLI/Command-Line-Interface/user.jpg?raw=true) - -7、点击新创建的用户 id，点击 Credentials 导航输入密码和关闭 Temporary 选项，至此 keyclork 配置完成 - -![avatar](/img/UserGuide/CLI/Command-Line-Interface/pwd.jpg?raw=true) - -8、创建角色，点击左侧菜单的 Roles然后点击Create Role 按钮添加角色 - -![avatar](/img/UserGuide/CLI/Command-Line-Interface/add_role1.jpg?raw=true) - -9、在Role Name 中输入`iotdb_admin`，点击save 按钮。提示：这里的`iotdb_admin`不能为其他名称否则即使登陆成功后也将无权限使用iotdb的查询、插入、创建 database、添加用户、角色等功能 - -![avatar](/img/UserGuide/CLI/Command-Line-Interface/add_role2.jpg?raw=true) - -10、点击左侧的User 菜单然后点击用户列表中的用户为该用户添加我们刚创建的`iotdb_admin`角色 - -![avatar](/img/UserGuide/CLI/Command-Line-Interface/add_role3.jpg?raw=true) - -11、选择Role Mappings ，在Assign role选择`iotdb_admin`增加角色 - -![avatar](/img/UserGuide/CLI/Command-Line-Interface/add_role4.jpg?raw=true) - -![avatar](/img/UserGuide/CLI/Command-Line-Interface/add_role5.jpg?raw=true) - -提示：如果用户角色有调整需要重新生成token并且重新登陆iotdb才会生效 - -以上步骤提供了一种 keycloak 登陆 iotdb 方式，更多方式请参考 keycloak 配置 - -若对应的 IoTDB 服务器开启了使用 OpenID Connect (OIDC) 作为权限认证服务，那么就不再需要使用用户名密码进行登录。 -替而代之的是使用 Token，以及空密码。 -此时，登录命令如下： - -```shell -Shell > bash sbin/start-cli.sh -h 10.129.187.21 -p 6667 -u {my-access-token} -pw "" -``` - -其中，需要将{my-access-token} （注意，包括{}）替换成你的 token，即 access_token 对应的值。密码为空需要再次确认。 - -![avatar](/img/UserGuide/CLI/Command-Line-Interface/iotdbpw.jpeg?raw=true) - -如何获取 token 取决于你的 OIDC 设置。 最简单的一种情况是使用`password-grant`。例如，假设你在用 keycloack 作为你的 OIDC 服务， -并且你在 keycloack 中有一个被定义成 public 的`iotdb`客户的 realm，那么你可以使用如下`curl`命令获得 token。 -（注意例子中的{}和里面的内容需要替换成具体的服务器地址和 realm 名字）： -```shell -curl -X POST "http://{your-keycloack-server}/realms/{your-realm}/protocol/openid-connect/token" \ -H "Content-Type: application/x-www-form-urlencoded" \ - -d "username={username}" \ - -d "password={password}" \ - -d 'grant_type=password' \ - -d "client_id=iotdb-client" -``` - -示例结果如下： - -```json -{"access_token":"eyJhbGciOiJSUzI1NiIsInR5cCIgOiAiSldUIiwia2lkIiA6ICJxMS1XbTBvelE1TzBtUUg4LVNKYXAyWmNONE1tdWNXd25RV0tZeFpKNG93In0.eyJleHAiOjE1OTAzOTgwNzEsImlhdCI6MTU5MDM5Nzc3MSwianRpIjoiNjA0ZmYxMDctN2NiNy00NTRmLWIwYmQtY2M2ZDQwMjFiNGU4IiwiaXNzIjoiaHR0cDovL2F1dGguZGVtby5wcmFnbWF0aWNpbmR1c3RyaWVzLmRlL2F1dGgvcmVhbG1zL0lvVERCIiwiYXVkIjoiYWNjb3VudCIsInN1YiI6ImJhMzJlNDcxLWM3NzItNGIzMy04ZGE2LTZmZThhY2RhMDA3MyIsInR5cCI6IkJlYXJlciIsImF6cCI6ImlvdGRiIiwic2Vzc2lvbl9zdGF0ZSI6IjA2MGQyODYyLTE0ZWQtNDJmZS1iYWY3LThkMWY3ODQ2NTdmMSIsImFjciI6IjEiLCJhbGxvd2VkLW9yaWdpbnMiOlsibG9jYWxob3N0OjgwODAiXSwicmVhbG1fYWNjZXNzIjp7InJvbGVzIjpbIm9mZmxpbmVfYWNjZXNzIiwidW1hX2F1dGhvcml6YXRpb24iLCJpb3RkYl9hZG1pbiJdfSwicmVzb3VyY2VfYWNjZXNzIjp7ImFjY291bnQiOnsicm9sZXMiOlsibWFuYWdlLWFjY291bnQiLCJtYW5hZ2UtYWNjb3VudC1saW5rcyIsInZpZXctcHJvZmlsZSJdfX0sInNjb3BlIjoiZW1haWwgcHJvZmlsZSIsImVtYWlsX3ZlcmlmaWVkIjp0cnVlLCJwcmVmZXJyZWRfdXNlcm5hbWUiOiJ1c2VyIn0.nwbrJkWdCNjzFrTDwKNuV5h9dDMg5ytRKGOXmFIajpfsbOutJytjWTCB2WpA8E1YI3KM6gU6Jx7cd7u0oPo5syHhfCz119n_wBiDnyTZkFOAPsx0M2z20kvBLN9k36_VfuCMFUeddJjO31MeLTmxB0UKg2VkxdczmzMH3pnalhxqpnWWk3GnrRrhAf2sZog0foH4Ae3Ks0lYtYzaWK_Yo7E4Px42-gJpohy3JevOC44aJ4auzJR1RBj9LUbgcRinkBy0JLi6XXiYznSC2V485CSBHW3sseXn7pSXQADhnmGQrLfFGO5ZljmPO18eFJaimdjvgSChsrlSEmTDDsoo5Q","expires_in":300,"refresh_expires_in":1800,"refresh_token":"eyJhbGciOiJIUzI1NiIsInR5cCIgOiAiSldUIiwia2lkIiA6ICJhMzZlMGU0NC02MWNmLTQ5NmMtOGRlZi03NTkwNjQ5MzQzMjEifQ.eyJleHAiOjE1OTAzOTk1NzEsImlhdCI6MTU5MDM5Nzc3MSwianRpIjoiNmMxNTBiY2EtYmE5NC00NTgxLWEwODEtYjI2YzhhMmI5YmZmIiwiaXNzIjoiaHR0cDovL2F1dGguZGVtby5wcmFnbWF0aWNpbmR1c3RyaWVzLmRlL2F1dGgvcmVhbG1zL0lvVERCIiwiYXVkIjoiaHR0cDovL2F1dGguZGVtby5wcmFnbWF0aWNpbmR1c3RyaWVzLmRlL2F1dGgvcmVhbG1zL0lvVERCIiwic3ViIjoiYmEzMmU0NzEtYzc3Mi00YjMzLThkYTYtNmZlOGFjZGEwMDczIiwidHlwIjoiUmVmcmVzaCIsImF6cCI6ImlvdGRiIiwic2Vzc2lvbl9zdGF0ZSI6IjA2MGQyODYyLTE0ZWQtNDJmZS1iYWY3LThkMWY3ODQ2NTdmMSIsInNjb3BlIjoiZW1haWwgcHJvZmlsZSJ9.ayNpXdNX28qahodX1zowrMGiUCw2AodlHBQFqr8Ui7c","token_type":"bearer","not-before-policy":0,"session_state":"060d2862-14ed-42fe-baf7-8d1f784657f1","scope":"email profile"} -``` - -### Cli 的批量操作 -当您想要通过脚本的方式通过 Cli / Shell 对 IoTDB 进行批量操作时，可以使用-e 参数。通过使用该参数，您可以在不进入客户端输入模式的情况下操作 IoTDB。 - -为了避免 SQL 语句和其他参数混淆，现在只支持-e 参数作为最后的参数使用。 - -针对 cli/Shell 工具的-e 参数用法如下： - -Linux 系统与 MacOS 指令： - -```shell -Shell > bash sbin/start-cli.sh -h {host} -p {rpcPort} -u {user} -pw {password} -e {sql for iotdb} -``` - -Windows 系统指令 -```shell -Shell > sbin\start-cli.bat -h {host} -p {rpcPort} -u {user} -pw {password} -e {sql for iotdb} -``` - -在 Windows 环境下，-e 参数的 SQL 语句需要使用` `` `对于`" "`进行替换 - -为了更好的解释-e 参数的使用，可以参考下面在 Linux 上执行的例子。 - -假设用户希望对一个新启动的 IoTDB 进行如下操作： - -1. 创建名为 root.demo 的 database - -2. 创建名为 root.demo.s1 的时间序列 - -3. 向创建的时间序列中插入三个数据点 - -4. 查询验证数据是否插入成功 - -那么通过使用 cli/Shell 工具的 -e 参数，可以采用如下的脚本： - -```shell -# !/bin/bash - -host=127.0.0.1 -rpcPort=6667 -user=root -pass=root - -bash ./sbin/start-cli.sh -h ${host} -p ${rpcPort} -u ${user} -pw ${pass} -e "CREATE DATABASE root.demo" -bash ./sbin/start-cli.sh -h ${host} -p ${rpcPort} -u ${user} -pw ${pass} -e "create timeseries root.demo.s1 WITH DATATYPE=INT32, ENCODING=RLE" -bash ./sbin/start-cli.sh -h ${host} -p ${rpcPort} -u ${user} -pw ${pass} -e "insert into root.demo(timestamp,s1) values(1,10)" -bash ./sbin/start-cli.sh -h ${host} -p ${rpcPort} -u ${user} -pw ${pass} -e "insert into root.demo(timestamp,s1) values(2,11)" -bash ./sbin/start-cli.sh -h ${host} -p ${rpcPort} -u ${user} -pw ${pass} -e "insert into root.demo(timestamp,s1) values(3,12)" -bash ./sbin/start-cli.sh -h ${host} -p ${rpcPort} -u ${user} -pw ${pass} -e "select s1 from root.demo" -``` - -打印出来的结果显示如下，通过这种方式进行的操作与客户端的输入模式以及通过 JDBC 进行操作结果是一致的。 - -```shell - Shell > bash ./shell.sh -+-----------------------------+------------+ -| Time|root.demo.s1| -+-----------------------------+------------+ -|1970-01-01T08:00:00.001+08:00| 10| -|1970-01-01T08:00:00.002+08:00| 11| -|1970-01-01T08:00:00.003+08:00| 12| -+-----------------------------+------------+ -Total line number = 3 -It costs 0.267s -``` - -需要特别注意的是，在脚本中使用 -e 参数时要对特殊字符进行转义。 - +--> \ No newline at end of file diff --git a/src/zh/UserGuide/dev-1.3/Tools-System/CLI_apache.md b/src/zh/UserGuide/dev-1.3/Tools-System/CLI_apache.md new file mode 100644 index 000000000..4e7125f51 --- /dev/null +++ b/src/zh/UserGuide/dev-1.3/Tools-System/CLI_apache.md @@ -0,0 +1,276 @@ + + +# SQL 命令行终端 (CLI) + +IOTDB 为用户提供 cli/Shell 工具用于启动客户端和服务端程序。下面介绍每个 cli/Shell 工具的运行方式和相关参数。 +> \$IOTDB\_HOME 表示 IoTDB 的安装目录所在路径。 + +## 安装 +如果使用源码版，可以在 iotdb 的根目录下执行 + +```shell +> mvn clean package -pl cli -am -DskipTests +``` + +在生成完毕之后，IoTDB 的 Cli 工具位于文件夹"cli/target/iotdb-cli-{project.version}"中。 + +如果你下载的是二进制版，那么 Cli 可以在 sbin 文件夹下直接找到。 + +## 运行 + +### Cli 运行方式 +安装后的 IoTDB 中有一个默认用户：`root`，默认密码为`root`。用户可以使用该用户尝试运行 IoTDB 客户端以测试服务器是否正常启动。客户端启动脚本为$IOTDB_HOME/sbin 文件夹下的`start-cli`脚本。启动脚本时需要指定运行 IP 和 RPC PORT。以下为服务器在本机启动，且用户未更改运行端口号的示例，默认端口为 6667。若用户尝试连接远程服务器或更改了服务器运行的端口号，请在-h 和-p 项处使用服务器的 IP 和 RPC PORT。
+用户也可以在启动脚本的最前方设置自己的环境变量，如 JAVA_HOME 等 （对于 linux 用户，脚本路径为："/sbin/start-cli.sh"； 对于 windows 用户，脚本路径为："/sbin/start-cli.bat") + +Linux 系统与 MacOS 系统启动命令如下： + +```shell +Shell > bash sbin/start-cli.sh -h 127.0.0.1 -p 6667 -u root -pw root +``` +Windows 系统启动命令如下： + +```shell +Shell > sbin\start-cli.bat -h 127.0.0.1 -p 6667 -u root -pw root +``` +回车后即可成功启动客户端。启动后出现如图提示即为启动成功。 + +``` + _____ _________ ______ ______ +|_ _| | _ _ ||_ _ `.|_ _ \ + | | .--.|_/ | | \_| | | `. \ | |_) | + | | / .'`\ \ | | | | | | | __'. + _| |_| \__. | _| |_ _| |_.' /_| |__) | +|_____|'.__.' |_____| |______.'|_______/ version + +Successfully login at 127.0.0.1:6667 +``` +输入`quit`或`exit`可退出 cli 结束本次会话，cli 输出`quit normally`表示退出成功。 + +### Cli 运行参数 + +|参数名|参数类型|是否为必需参数| 说明| 例子 | +|:---|:---|:---|:---|:---| +|-disableISO8601 |没有参数 | 否 |如果设置了这个参数，IoTDB 将以数字的形式打印时间戳 (timestamp)。|-disableISO8601| +|-h <`host`> |string 类型，不需要引号|是|IoTDB 客户端连接 IoTDB 服务器的 IP 地址。|-h 10.129.187.21| +|-help|没有参数|否|打印 IoTDB 的帮助信息|-help| +|-p <`rpcPort`>|int 类型|是|IoTDB 连接服务器的端口号，IoTDB 默认运行在 6667 端口。|-p 6667| +|-pw <`password`>|string 类型，不需要引号|否|IoTDB 连接服务器所使用的密码。如果没有输入密码 IoTDB 会在 Cli 端提示输入密码。|-pw root| +|-u <`username`>|string 类型，不需要引号|是|IoTDB 连接服务器锁使用的用户名。|-u root| +|-maxPRC <`maxPrintRowCount`>|int 类型|否|设置 IoTDB 返回客户端命令行中所显示的最大行数。|-maxPRC 10| +|-e <`execute`> |string 类型|否|在不进入客户端输入模式的情况下，批量操作 IoTDB|-e "show databases"| +|-c | 空 | 否 | 如果服务器设置了 `rpc_thrift_compression_enable=true`, 则 CLI 必须使用 `-c` | -c | + +下面展示一条客户端命令，功能是连接 IP 为 10.129.187.21 的主机，端口为 6667 ，用户名为 root，密码为 root，以数字的形式打印时间戳，IoTDB 命令行显示的最大行数为 10。 + +Linux 系统与 MacOS 系统启动命令如下： + +```shell +Shell > bash sbin/start-cli.sh -h 10.129.187.21 -p 6667 -u root -pw root -disableISO8601 -maxPRC 10 +``` +Windows 系统启动命令如下： + +```shell +Shell > sbin\start-cli.bat -h 10.129.187.21 -p 6667 -u root -pw root -disableISO8601 -maxPRC 10 +``` + +### CLI 特殊命令 +下面列举了一些CLI的特殊命令。 + +| 命令 | 描述 / 例子 | +|:---|:---| +| `set time_display_type=xxx` | 例如： long, default, ISO8601, yyyy-MM-dd HH:mm:ss | +| `show time_display_type` | 显示时间显示方式 | +| `set time_zone=xxx` | 例如： +08:00, Asia/Shanghai | +| `show time_zone` | 显示CLI的时区 | +| `set fetch_size=xxx` | 设置从服务器查询数据时的读取条数 | +| `show fetch_size` | 显示读取条数的大小 | +| `set max_display_num=xxx` | 设置 CLI 一次展示的最大数据条数， 设置为-1表示无限制 | +| `help` | 获取CLI特殊命令的提示 | +| `exit/quit` | 退出CLI | + +### 使用 OpenID 作为用户名认证登录 + +OpenID Connect (OIDC) 使用 keycloack 作为 OIDC 服务权限认证服务。 + +#### 配置 +配置位于 iotdb-system.properties，设定 authorizer_provider_class 为 org.apache.iotdb.commons.auth.authorizer.OpenIdAuthorizer 则开启了 openID 服务，默认情况下值为 org.apache.iotdb.commons.auth.authorizer.LocalFileAuthorizer 表示没有开启 openID 服务。 + +``` +authorizer_provider_class=org.apache.iotdb.commons.auth.authorizer.OpenIdAuthorizer +``` +如果开启了 openID 服务则 openID_url 为必填项，openID_url 值为 http://ip:port/realms/{realmsName} + +``` +openID_url=http://127.0.0.1:8080/realms/iotdb/ +``` +#### keycloack 配置 + +1、下载 keycloack 程序（此教程为21.1.0版本），在 keycloack/bin 中启动 keycloack + +```shell +Shell > cd bin +Shell > ./kc.sh start-dev +``` +2、使用 https://ip:port 登陆 keycloack, 首次登陆需要创建用户 + +![avatar](/img/UserGuide/CLI/Command-Line-Interface/login_keycloak.png?raw=true) + +3、点击 Administration Console 进入管理端 + +![avatar](/img/UserGuide/CLI/Command-Line-Interface/AdministrationConsole.png?raw=true) + +4、在左侧的 Master 菜单点击 Create Realm, 输入 Realm Name 创建一个新的 Realm + +![avatar](/img/UserGuide/CLI/Command-Line-Interface/add_Realm_1.jpg?raw=true) + +![avatar](/img/UserGuide/CLI/Command-Line-Interface/add_Realm_2.jpg?raw=true) + +5、点击左侧菜单 Clients，创建 client + +![avatar](/img/UserGuide/CLI/Command-Line-Interface/client.jpg?raw=true) + +6、点击左侧菜单 User，创建 user + +![avatar](/img/UserGuide/CLI/Command-Line-Interface/user.jpg?raw=true) + +7、点击新创建的用户 id，点击 Credentials 导航输入密码和关闭 Temporary 选项，至此 keyclork 配置完成 + +![avatar](/img/UserGuide/CLI/Command-Line-Interface/pwd.jpg?raw=true) + +8、创建角色，点击左侧菜单的 Roles然后点击Create Role 按钮添加角色 + +![avatar](/img/UserGuide/CLI/Command-Line-Interface/add_role1.jpg?raw=true) + +9、在Role Name 中输入`iotdb_admin`，点击save 按钮。提示：这里的`iotdb_admin`不能为其他名称否则即使登陆成功后也将无权限使用iotdb的查询、插入、创建 database、添加用户、角色等功能 + +![avatar](/img/UserGuide/CLI/Command-Line-Interface/add_role2.jpg?raw=true) + +10、点击左侧的User 菜单然后点击用户列表中的用户为该用户添加我们刚创建的`iotdb_admin`角色 + +![avatar](/img/UserGuide/CLI/Command-Line-Interface/add_role3.jpg?raw=true) + +11、选择Role Mappings ，在Assign role选择`iotdb_admin`增加角色 + +![avatar](/img/UserGuide/CLI/Command-Line-Interface/add_role4.jpg?raw=true) + +![avatar](/img/UserGuide/CLI/Command-Line-Interface/add_role5.jpg?raw=true) + +提示：如果用户角色有调整需要重新生成token并且重新登陆iotdb才会生效 + +以上步骤提供了一种 keycloak 登陆 iotdb 方式，更多方式请参考 keycloak 配置 + +若对应的 IoTDB 服务器开启了使用 OpenID Connect (OIDC) 作为权限认证服务，那么就不再需要使用用户名密码进行登录。 +替而代之的是使用 Token，以及空密码。 +此时，登录命令如下： + +```shell +Shell > bash sbin/start-cli.sh -h 10.129.187.21 -p 6667 -u {my-access-token} -pw "" +``` + +其中，需要将{my-access-token} （注意，包括{}）替换成你的 token，即 access_token 对应的值。密码为空需要再次确认。 + +![avatar](/img/UserGuide/CLI/Command-Line-Interface/iotdbpw.jpeg?raw=true) + +如何获取 token 取决于你的 OIDC 设置。 最简单的一种情况是使用`password-grant`。例如，假设你在用 keycloack 作为你的 OIDC 服务， +并且你在 keycloack 中有一个被定义成 public 的`iotdb`客户的 realm，那么你可以使用如下`curl`命令获得 token。 +（注意例子中的{}和里面的内容需要替换成具体的服务器地址和 realm 名字）： +```shell +curl -X POST "http://{your-keycloack-server}/realms/{your-realm}/protocol/openid-connect/token" \ -H "Content-Type: application/x-www-form-urlencoded" \ + -d "username={username}" \ + -d "password={password}" \ + -d 'grant_type=password' \ + -d "client_id=iotdb-client" +``` + +示例结果如下： + +```json +{"access_token":"eyJhbGciOiJSUzI1NiIsInR5cCIgOiAiSldUIiwia2lkIiA6ICJxMS1XbTBvelE1TzBtUUg4LVNKYXAyWmNONE1tdWNXd25RV0tZeFpKNG93In0.eyJleHAiOjE1OTAzOTgwNzEsImlhdCI6MTU5MDM5Nzc3MSwianRpIjoiNjA0ZmYxMDctN2NiNy00NTRmLWIwYmQtY2M2ZDQwMjFiNGU4IiwiaXNzIjoiaHR0cDovL2F1dGguZGVtby5wcmFnbWF0aWNpbmR1c3RyaWVzLmRlL2F1dGgvcmVhbG1zL0lvVERCIiwiYXVkIjoiYWNjb3VudCIsInN1YiI6ImJhMzJlNDcxLWM3NzItNGIzMy04ZGE2LTZmZThhY2RhMDA3MyIsInR5cCI6IkJlYXJlciIsImF6cCI6ImlvdGRiIiwic2Vzc2lvbl9zdGF0ZSI6IjA2MGQyODYyLTE0ZWQtNDJmZS1iYWY3LThkMWY3ODQ2NTdmMSIsImFjciI6IjEiLCJhbGxvd2VkLW9yaWdpbnMiOlsibG9jYWxob3N0OjgwODAiXSwicmVhbG1fYWNjZXNzIjp7InJvbGVzIjpbIm9mZmxpbmVfYWNjZXNzIiwidW1hX2F1dGhvcml6YXRpb24iLCJpb3RkYl9hZG1pbiJdfSwicmVzb3VyY2VfYWNjZXNzIjp7ImFjY291bnQiOnsicm9sZXMiOlsibWFuYWdlLWFjY291bnQiLCJtYW5hZ2UtYWNjb3VudC1saW5rcyIsInZpZXctcHJvZmlsZSJdfX0sInNjb3BlIjoiZW1haWwgcHJvZmlsZSIsImVtYWlsX3ZlcmlmaWVkIjp0cnVlLCJwcmVmZXJyZWRfdXNlcm5hbWUiOiJ1c2VyIn0.nwbrJkWdCNjzFrTDwKNuV5h9dDMg5ytRKGOXmFIajpfsbOutJytjWTCB2WpA8E1YI3KM6gU6Jx7cd7u0oPo5syHhfCz119n_wBiDnyTZkFOAPsx0M2z20kvBLN9k36_VfuCMFUeddJjO31MeLTmxB0UKg2VkxdczmzMH3pnalhxqpnWWk3GnrRrhAf2sZog0foH4Ae3Ks0lYtYzaWK_Yo7E4Px42-gJpohy3JevOC44aJ4auzJR1RBj9LUbgcRinkBy0JLi6XXiYznSC2V485CSBHW3sseXn7pSXQADhnmGQrLfFGO5ZljmPO18eFJaimdjvgSChsrlSEmTDDsoo5Q","expires_in":300,"refresh_expires_in":1800,"refresh_token":"eyJhbGciOiJIUzI1NiIsInR5cCIgOiAiSldUIiwia2lkIiA6ICJhMzZlMGU0NC02MWNmLTQ5NmMtOGRlZi03NTkwNjQ5MzQzMjEifQ.eyJleHAiOjE1OTAzOTk1NzEsImlhdCI6MTU5MDM5Nzc3MSwianRpIjoiNmMxNTBiY2EtYmE5NC00NTgxLWEwODEtYjI2YzhhMmI5YmZmIiwiaXNzIjoiaHR0cDovL2F1dGguZGVtby5wcmFnbWF0aWNpbmR1c3RyaWVzLmRlL2F1dGgvcmVhbG1zL0lvVERCIiwiYXVkIjoiaHR0cDovL2F1dGguZGVtby5wcmFnbWF0aWNpbmR1c3RyaWVzLmRlL2F1dGgvcmVhbG1zL0lvVERCIiwic3ViIjoiYmEzMmU0NzEtYzc3Mi00YjMzLThkYTYtNmZlOGFjZGEwMDczIiwidHlwIjoiUmVmcmVzaCIsImF6cCI6ImlvdGRiIiwic2Vzc2lvbl9zdGF0ZSI6IjA2MGQyODYyLTE0ZWQtNDJmZS1iYWY3LThkMWY3ODQ2NTdmMSIsInNjb3BlIjoiZW1haWwgcHJvZmlsZSJ9.ayNpXdNX28qahodX1zowrMGiUCw2AodlHBQFqr8Ui7c","token_type":"bearer","not-before-policy":0,"session_state":"060d2862-14ed-42fe-baf7-8d1f784657f1","scope":"email profile"} +``` + +### Cli 的批量操作 +当您想要通过脚本的方式通过 Cli / Shell 对 IoTDB 进行批量操作时，可以使用-e 参数。通过使用该参数，您可以在不进入客户端输入模式的情况下操作 IoTDB。 + +为了避免 SQL 语句和其他参数混淆，现在只支持-e 参数作为最后的参数使用。 + +针对 cli/Shell 工具的-e 参数用法如下： + +Linux 系统与 MacOS 指令： + +```shell +Shell > bash sbin/start-cli.sh -h {host} -p {rpcPort} -u {user} -pw {password} -e {sql for iotdb} +``` + +Windows 系统指令 +```shell +Shell > sbin\start-cli.bat -h {host} -p {rpcPort} -u {user} -pw {password} -e {sql for iotdb} +``` + +在 Windows 环境下，-e 参数的 SQL 语句需要使用` `` `对于`" "`进行替换 + +为了更好的解释-e 参数的使用，可以参考下面在 Linux 上执行的例子。 + +假设用户希望对一个新启动的 IoTDB 进行如下操作： + +1. 创建名为 root.demo 的 database + +2. 创建名为 root.demo.s1 的时间序列 + +3. 向创建的时间序列中插入三个数据点 + +4. 查询验证数据是否插入成功 + +那么通过使用 cli/Shell 工具的 -e 参数，可以采用如下的脚本： + +```shell +# !/bin/bash + +host=127.0.0.1 +rpcPort=6667 +user=root +pass=root + +bash ./sbin/start-cli.sh -h ${host} -p ${rpcPort} -u ${user} -pw ${pass} -e "CREATE DATABASE root.demo" +bash ./sbin/start-cli.sh -h ${host} -p ${rpcPort} -u ${user} -pw ${pass} -e "create timeseries root.demo.s1 WITH DATATYPE=INT32, ENCODING=RLE" +bash ./sbin/start-cli.sh -h ${host} -p ${rpcPort} -u ${user} -pw ${pass} -e "insert into root.demo(timestamp,s1) values(1,10)" +bash ./sbin/start-cli.sh -h ${host} -p ${rpcPort} -u ${user} -pw ${pass} -e "insert into root.demo(timestamp,s1) values(2,11)" +bash ./sbin/start-cli.sh -h ${host} -p ${rpcPort} -u ${user} -pw ${pass} -e "insert into root.demo(timestamp,s1) values(3,12)" +bash ./sbin/start-cli.sh -h ${host} -p ${rpcPort} -u ${user} -pw ${pass} -e "select s1 from root.demo" +``` + +打印出来的结果显示如下，通过这种方式进行的操作与客户端的输入模式以及通过 JDBC 进行操作结果是一致的。 + +```shell + Shell > bash ./shell.sh ++-----------------------------+------------+ +| Time|root.demo.s1| ++-----------------------------+------------+ +|1970-01-01T08:00:00.001+08:00| 10| +|1970-01-01T08:00:00.002+08:00| 11| +|1970-01-01T08:00:00.003+08:00| 12| ++-----------------------------+------------+ +Total line number = 3 +It costs 0.267s +``` + +需要特别注意的是，在脚本中使用 -e 参数时要对特殊字符进行转义。 + diff --git a/src/zh/UserGuide/dev-1.3/Tools-System/CLI_timecho.md b/src/zh/UserGuide/dev-1.3/Tools-System/CLI_timecho.md new file mode 100644 index 000000000..e8fc508bd --- /dev/null +++ b/src/zh/UserGuide/dev-1.3/Tools-System/CLI_timecho.md @@ -0,0 +1,263 @@ + + +# SQL 命令行终端 (CLI) + +IOTDB 为用户提供 cli/Shell 工具用于启动客户端和服务端程序。下面介绍每个 cli/Shell 工具的运行方式和相关参数。 +> \$IOTDB\_HOME 表示 IoTDB 的安装目录所在路径。 + +## Cli 运行方式 +安装后的 IoTDB 中有一个默认用户：`root`，默认密码为`root`。用户可以使用该用户尝试运行 IoTDB 客户端以测试服务器是否正常启动。客户端启动脚本为$IOTDB_HOME/sbin 文件夹下的`start-cli`脚本。启动脚本时需要指定运行 IP 和 RPC PORT。以下为服务器在本机启动，且用户未更改运行端口号的示例，默认端口为 6667。若用户尝试连接远程服务器或更改了服务器运行的端口号，请在-h 和-p 项处使用服务器的 IP 和 RPC PORT。
+用户也可以在启动脚本的最前方设置自己的环境变量，如 JAVA_HOME 等 （对于 linux 用户，脚本路径为："/sbin/start-cli.sh"； 对于 windows 用户，脚本路径为："/sbin/start-cli.bat") + +Linux 系统与 MacOS 系统启动命令如下： + +```shell +Shell > bash sbin/start-cli.sh -h 127.0.0.1 -p 6667 -u root -pw root +``` +Windows 系统启动命令如下： + +```shell +Shell > sbin\start-cli.bat -h 127.0.0.1 -p 6667 -u root -pw root +``` +回车后即可成功启动客户端。启动后出现如图提示即为启动成功。 + +``` + _____ _________ ______ ______ +|_ _| | _ _ ||_ _ `.|_ _ \ + | | .--.|_/ | | \_| | | `. \ | |_) | + | | / .'`\ \ | | | | | | | __'. + _| |_| \__. | _| |_ _| |_.' /_| |__) | +|_____|'.__.' |_____| |______.'|_______/ version + +Successfully login at 127.0.0.1:6667 +``` +输入`quit`或`exit`可退出 cli 结束本次会话，cli 输出`quit normally`表示退出成功。 + +## Cli 运行参数 + +|参数名|参数类型|是否为必需参数| 说明| 例子 | +|:---|:---|:---|:---|:---| +|-disableISO8601 |没有参数 | 否 |如果设置了这个参数，IoTDB 将以数字的形式打印时间戳 (timestamp)。|-disableISO8601| +|-h <`host`> |string 类型，不需要引号|是|IoTDB 客户端连接 IoTDB 服务器的 IP 地址。|-h 10.129.187.21| +|-help|没有参数|否|打印 IoTDB 的帮助信息|-help| +|-p <`rpcPort`>|int 类型|是|IoTDB 连接服务器的端口号，IoTDB 默认运行在 6667 端口。|-p 6667| +|-pw <`password`>|string 类型，不需要引号|否|IoTDB 连接服务器所使用的密码。如果没有输入密码 IoTDB 会在 Cli 端提示输入密码。|-pw root| +|-u <`username`>|string 类型，不需要引号|是|IoTDB 连接服务器锁使用的用户名。|-u root| +|-maxPRC <`maxPrintRowCount`>|int 类型|否|设置 IoTDB 返回客户端命令行中所显示的最大行数。|-maxPRC 10| +|-e <`execute`> |string 类型|否|在不进入客户端输入模式的情况下，批量操作 IoTDB|-e "show databases"| +|-c | 空 | 否 | 如果服务器设置了 `rpc_thrift_compression_enable=true`, 则 CLI 必须使用 `-c` | -c | + +下面展示一条客户端命令，功能是连接 IP 为 10.129.187.21 的主机，端口为 6667 ，用户名为 root，密码为 root，以数字的形式打印时间戳，IoTDB 命令行显示的最大行数为 10。 + +Linux 系统与 MacOS 系统启动命令如下： + +```shell +Shell > bash sbin/start-cli.sh -h 10.129.187.21 -p 6667 -u root -pw root -disableISO8601 -maxPRC 10 +``` +Windows 系统启动命令如下： + +```shell +Shell > sbin\start-cli.bat -h 10.129.187.21 -p 6667 -u root -pw root -disableISO8601 -maxPRC 10 +``` + +## CLI 特殊命令 +下面列举了一些CLI的特殊命令。 + +| 命令 | 描述 / 例子 | +|:---|:---| +| `set time_display_type=xxx` | 例如： long, default, ISO8601, yyyy-MM-dd HH:mm:ss | +| `show time_display_type` | 显示时间显示方式 | +| `set time_zone=xxx` | 例如： +08:00, Asia/Shanghai | +| `show time_zone` | 显示CLI的时区 | +| `set fetch_size=xxx` | 设置从服务器查询数据时的读取条数 | +| `show fetch_size` | 显示读取条数的大小 | +| `set max_display_num=xxx` | 设置 CLI 一次展示的最大数据条数， 设置为-1表示无限制 | +| `help` | 获取CLI特殊命令的提示 | +| `exit/quit` | 退出CLI | + +## 使用 OpenID 作为用户名认证登录 + +OpenID Connect (OIDC) 使用 keycloack 作为 OIDC 服务权限认证服务。 + +### 配置 +配置位于 iotdb-system.properties，设定 authorizer_provider_class 为 org.apache.iotdb.commons.auth.authorizer.OpenIdAuthorizer 则开启了 openID 服务，默认情况下值为 org.apache.iotdb.commons.auth.authorizer.LocalFileAuthorizer 表示没有开启 openID 服务。 + +``` +authorizer_provider_class=org.apache.iotdb.commons.auth.authorizer.OpenIdAuthorizer +``` +如果开启了 openID 服务则 openID_url 为必填项，openID_url 值为 http://ip:port/realms/{realmsName} + +``` +openID_url=http://127.0.0.1:8080/realms/iotdb/ +``` +### keycloack 配置 + +1、下载 keycloack 程序（此教程为21.1.0版本），在 keycloack/bin 中启动 keycloack + +```shell +Shell > cd bin +Shell > ./kc.sh start-dev +``` +2、使用 https://ip:port 登陆 keycloack, 首次登陆需要创建用户 + +![avatar](/img/UserGuide/CLI/Command-Line-Interface/login_keycloak.png?raw=true) + +3、点击 Administration Console 进入管理端 + +![avatar](/img/UserGuide/CLI/Command-Line-Interface/AdministrationConsole.png?raw=true) + +4、在左侧的 Master 菜单点击 Create Realm, 输入 Realm Name 创建一个新的 Realm + +![avatar](/img/UserGuide/CLI/Command-Line-Interface/add_Realm_1.jpg?raw=true) + +![avatar](/img/UserGuide/CLI/Command-Line-Interface/add_Realm_2.jpg?raw=true) + +5、点击左侧菜单 Clients，创建 client + +![avatar](/img/UserGuide/CLI/Command-Line-Interface/client.jpg?raw=true) + +6、点击左侧菜单 User，创建 user + +![avatar](/img/UserGuide/CLI/Command-Line-Interface/user.jpg?raw=true) + +7、点击新创建的用户 id，点击 Credentials 导航输入密码和关闭 Temporary 选项，至此 keyclork 配置完成 + +![avatar](/img/UserGuide/CLI/Command-Line-Interface/pwd.jpg?raw=true) + +8、创建角色，点击左侧菜单的 Roles然后点击Create Role 按钮添加角色 + +![avatar](/img/UserGuide/CLI/Command-Line-Interface/add_role1.jpg?raw=true) + +9、在Role Name 中输入`iotdb_admin`，点击save 按钮。提示：这里的`iotdb_admin`不能为其他名称否则即使登陆成功后也将无权限使用iotdb的查询、插入、创建 database、添加用户、角色等功能 + +![avatar](/img/UserGuide/CLI/Command-Line-Interface/add_role2.jpg?raw=true) + +10、点击左侧的User 菜单然后点击用户列表中的用户为该用户添加我们刚创建的`iotdb_admin`角色 + +![avatar](/img/UserGuide/CLI/Command-Line-Interface/add_role3.jpg?raw=true) + +11、选择Role Mappings ，在Assign role选择`iotdb_admin`增加角色 + +![avatar](/img/UserGuide/CLI/Command-Line-Interface/add_role4.jpg?raw=true) + +![avatar](/img/UserGuide/CLI/Command-Line-Interface/add_role5.jpg?raw=true) + +提示：如果用户角色有调整需要重新生成token并且重新登陆iotdb才会生效 + +以上步骤提供了一种 keycloak 登陆 iotdb 方式，更多方式请参考 keycloak 配置 + +若对应的 IoTDB 服务器开启了使用 OpenID Connect (OIDC) 作为权限认证服务，那么就不再需要使用用户名密码进行登录。 +替而代之的是使用 Token，以及空密码。 +此时，登录命令如下： + +```shell +Shell > bash sbin/start-cli.sh -h 10.129.187.21 -p 6667 -u {my-access-token} -pw "" +``` + +其中，需要将{my-access-token} （注意，包括{}）替换成你的 token，即 access_token 对应的值。密码为空需要再次确认。 + +![avatar](/img/UserGuide/CLI/Command-Line-Interface/iotdbpw.jpeg?raw=true) + +如何获取 token 取决于你的 OIDC 设置。 最简单的一种情况是使用`password-grant`。例如，假设你在用 keycloack 作为你的 OIDC 服务， +并且你在 keycloack 中有一个被定义成 public 的`iotdb`客户的 realm，那么你可以使用如下`curl`命令获得 token。 +（注意例子中的{}和里面的内容需要替换成具体的服务器地址和 realm 名字）： +```shell +curl -X POST "http://{your-keycloack-server}/realms/{your-realm}/protocol/openid-connect/token" \ -H "Content-Type: application/x-www-form-urlencoded" \ + -d "username={username}" \ + -d "password={password}" \ + -d 'grant_type=password' \ + -d "client_id=iotdb-client" +``` + +示例结果如下： + +```json +{"access_token":"eyJhbGciOiJSUzI1NiIsInR5cCIgOiAiSldUIiwia2lkIiA6ICJxMS1XbTBvelE1TzBtUUg4LVNKYXAyWmNONE1tdWNXd25RV0tZeFpKNG93In0.eyJleHAiOjE1OTAzOTgwNzEsImlhdCI6MTU5MDM5Nzc3MSwianRpIjoiNjA0ZmYxMDctN2NiNy00NTRmLWIwYmQtY2M2ZDQwMjFiNGU4IiwiaXNzIjoiaHR0cDovL2F1dGguZGVtby5wcmFnbWF0aWNpbmR1c3RyaWVzLmRlL2F1dGgvcmVhbG1zL0lvVERCIiwiYXVkIjoiYWNjb3VudCIsInN1YiI6ImJhMzJlNDcxLWM3NzItNGIzMy04ZGE2LTZmZThhY2RhMDA3MyIsInR5cCI6IkJlYXJlciIsImF6cCI6ImlvdGRiIiwic2Vzc2lvbl9zdGF0ZSI6IjA2MGQyODYyLTE0ZWQtNDJmZS1iYWY3LThkMWY3ODQ2NTdmMSIsImFjciI6IjEiLCJhbGxvd2VkLW9yaWdpbnMiOlsibG9jYWxob3N0OjgwODAiXSwicmVhbG1fYWNjZXNzIjp7InJvbGVzIjpbIm9mZmxpbmVfYWNjZXNzIiwidW1hX2F1dGhvcml6YXRpb24iLCJpb3RkYl9hZG1pbiJdfSwicmVzb3VyY2VfYWNjZXNzIjp7ImFjY291bnQiOnsicm9sZXMiOlsibWFuYWdlLWFjY291bnQiLCJtYW5hZ2UtYWNjb3VudC1saW5rcyIsInZpZXctcHJvZmlsZSJdfX0sInNjb3BlIjoiZW1haWwgcHJvZmlsZSIsImVtYWlsX3ZlcmlmaWVkIjp0cnVlLCJwcmVmZXJyZWRfdXNlcm5hbWUiOiJ1c2VyIn0.nwbrJkWdCNjzFrTDwKNuV5h9dDMg5ytRKGOXmFIajpfsbOutJytjWTCB2WpA8E1YI3KM6gU6Jx7cd7u0oPo5syHhfCz119n_wBiDnyTZkFOAPsx0M2z20kvBLN9k36_VfuCMFUeddJjO31MeLTmxB0UKg2VkxdczmzMH3pnalhxqpnWWk3GnrRrhAf2sZog0foH4Ae3Ks0lYtYzaWK_Yo7E4Px42-gJpohy3JevOC44aJ4auzJR1RBj9LUbgcRinkBy0JLi6XXiYznSC2V485CSBHW3sseXn7pSXQADhnmGQrLfFGO5ZljmPO18eFJaimdjvgSChsrlSEmTDDsoo5Q","expires_in":300,"refresh_expires_in":1800,"refresh_token":"eyJhbGciOiJIUzI1NiIsInR5cCIgOiAiSldUIiwia2lkIiA6ICJhMzZlMGU0NC02MWNmLTQ5NmMtOGRlZi03NTkwNjQ5MzQzMjEifQ.eyJleHAiOjE1OTAzOTk1NzEsImlhdCI6MTU5MDM5Nzc3MSwianRpIjoiNmMxNTBiY2EtYmE5NC00NTgxLWEwODEtYjI2YzhhMmI5YmZmIiwiaXNzIjoiaHR0cDovL2F1dGguZGVtby5wcmFnbWF0aWNpbmR1c3RyaWVzLmRlL2F1dGgvcmVhbG1zL0lvVERCIiwiYXVkIjoiaHR0cDovL2F1dGguZGVtby5wcmFnbWF0aWNpbmR1c3RyaWVzLmRlL2F1dGgvcmVhbG1zL0lvVERCIiwic3ViIjoiYmEzMmU0NzEtYzc3Mi00YjMzLThkYTYtNmZlOGFjZGEwMDczIiwidHlwIjoiUmVmcmVzaCIsImF6cCI6ImlvdGRiIiwic2Vzc2lvbl9zdGF0ZSI6IjA2MGQyODYyLTE0ZWQtNDJmZS1iYWY3LThkMWY3ODQ2NTdmMSIsInNjb3BlIjoiZW1haWwgcHJvZmlsZSJ9.ayNpXdNX28qahodX1zowrMGiUCw2AodlHBQFqr8Ui7c","token_type":"bearer","not-before-policy":0,"session_state":"060d2862-14ed-42fe-baf7-8d1f784657f1","scope":"email profile"} +``` + +## Cli 的批量操作 +当您想要通过脚本的方式通过 Cli / Shell 对 IoTDB 进行批量操作时，可以使用-e 参数。通过使用该参数，您可以在不进入客户端输入模式的情况下操作 IoTDB。 + +为了避免 SQL 语句和其他参数混淆，现在只支持-e 参数作为最后的参数使用。 + +针对 cli/Shell 工具的-e 参数用法如下： + +Linux 系统与 MacOS 指令： + +```shell +Shell > bash sbin/start-cli.sh -h {host} -p {rpcPort} -u {user} -pw {password} -e {sql for iotdb} +``` + +Windows 系统指令 +```shell +Shell > sbin\start-cli.bat -h {host} -p {rpcPort} -u {user} -pw {password} -e {sql for iotdb} +``` + +在 Windows 环境下，-e 参数的 SQL 语句需要使用` `` `对于`" "`进行替换 + +为了更好的解释-e 参数的使用，可以参考下面在 Linux 上执行的例子。 + +假设用户希望对一个新启动的 IoTDB 进行如下操作： + +1. 创建名为 root.demo 的 database + +2. 创建名为 root.demo.s1 的时间序列 + +3. 向创建的时间序列中插入三个数据点 + +4. 查询验证数据是否插入成功 + +那么通过使用 cli/Shell 工具的 -e 参数，可以采用如下的脚本： + +```shell +# !/bin/bash + +host=127.0.0.1 +rpcPort=6667 +user=root +pass=root + +bash ./sbin/start-cli.sh -h ${host} -p ${rpcPort} -u ${user} -pw ${pass} -e "CREATE DATABASE root.demo" +bash ./sbin/start-cli.sh -h ${host} -p ${rpcPort} -u ${user} -pw ${pass} -e "create timeseries root.demo.s1 WITH DATATYPE=INT32, ENCODING=RLE" +bash ./sbin/start-cli.sh -h ${host} -p ${rpcPort} -u ${user} -pw ${pass} -e "insert into root.demo(timestamp,s1) values(1,10)" +bash ./sbin/start-cli.sh -h ${host} -p ${rpcPort} -u ${user} -pw ${pass} -e "insert into root.demo(timestamp,s1) values(2,11)" +bash ./sbin/start-cli.sh -h ${host} -p ${rpcPort} -u ${user} -pw ${pass} -e "insert into root.demo(timestamp,s1) values(3,12)" +bash ./sbin/start-cli.sh -h ${host} -p ${rpcPort} -u ${user} -pw ${pass} -e "select s1 from root.demo" +``` + +打印出来的结果显示如下，通过这种方式进行的操作与客户端的输入模式以及通过 JDBC 进行操作结果是一致的。 + +```shell + Shell > bash ./shell.sh ++-----------------------------+------------+ +| Time|root.demo.s1| ++-----------------------------+------------+ +|1970-01-01T08:00:00.001+08:00| 10| +|1970-01-01T08:00:00.002+08:00| 11| +|1970-01-01T08:00:00.003+08:00| 12| ++-----------------------------+------------+ +Total line number = 3 +It costs 0.267s +``` + +需要特别注意的是，在脚本中使用 -e 参数时要对特殊字符进行转义。 + diff --git a/src/zh/UserGuide/latest/Tools-System/CLI.md b/src/zh/UserGuide/latest/Tools-System/CLI.md index 23d3470bc..03580fafb 100644 --- a/src/zh/UserGuide/latest/Tools-System/CLI.md +++ b/src/zh/UserGuide/latest/Tools-System/CLI.md @@ -1,3 +1,6 @@ +--- +redirectTo: CLI_apache.html +--- - -# 命令行工具 - -IOTDB 为用户提供 cli/Shell 工具用于启动客户端和服务端程序。下面介绍每个 cli/Shell 工具的运行方式和相关参数。 -> \$IOTDB\_HOME 表示 IoTDB 的安装目录所在路径。 - -## 1. 安装 -如果使用源码版，可以在 iotdb 的根目录下执行 - -```shell -> mvn clean package -pl cli -am -DskipTests -``` - -在生成完毕之后，IoTDB 的 Cli 工具位于文件夹"cli/target/iotdb-cli-{project.version}"中。 - -如果你下载的是二进制版，那么 Cli 可以在 sbin 文件夹下直接找到。 - -## 2. 运行 - -### 2.1 Cli 运行方式 -安装后的 IoTDB 中有一个默认用户：`root`，默认密码为`root`。用户可以使用该用户尝试运行 IoTDB 客户端以测试服务器是否正常启动。客户端启动脚本为$IOTDB_HOME/sbin 文件夹下的`start-cli`脚本。启动脚本时需要指定运行 IP 和 RPC PORT。以下为服务器在本机启动，且用户未更改运行端口号的示例，默认端口为 6667。若用户尝试连接远程服务器或更改了服务器运行的端口号，请在-h 和-p 项处使用服务器的 IP 和 RPC PORT。
-用户也可以在启动脚本的最前方设置自己的环境变量，如 JAVA_HOME 等。 - -Linux 系统与 MacOS 系统启动命令如下： - -```shell -Shell > bash sbin/start-cli.sh -h 127.0.0.1 -p 6667 -u root -pw root -``` -Windows 系统启动命令如下： - -```shell -# V2.0.4.x 版本之前 -Shell > sbin\start-cli.bat -h 127.0.0.1 -p 6667 -u root -pw root - -# V2.0.4.x 版本及之后 -Shell > sbin\windows\start-cli.bat -h 127.0.0.1 -p 6667 -u root -pw root -``` -回车后即可成功启动客户端。启动后出现如图提示即为启动成功。 - -``` - _____ _________ ______ ______ -|_ _| | _ _ ||_ _ `.|_ _ \ - | | .--.|_/ | | \_| | | `. \ | |_) | - | | / .'`\ \ | | | | | | | __'. - _| |_| \__. | _| |_ _| |_.' /_| |__) | -|_____|'.__.' |_____| |______.'|_______/ version - -Successfully login at 127.0.0.1:6667 -``` -输入`quit`或`exit`可退出 cli 结束本次会话，cli 输出`quit normally`表示退出成功。 - -### 2.2 Cli 运行参数 - -|参数名|参数类型|是否为必需参数| 说明| 例子 | -|:---|:---|:---|:---|:---| -|-disableISO8601 |没有参数 | 否 |如果设置了这个参数，IoTDB 将以数字的形式打印时间戳 (timestamp)。|-disableISO8601| -|-h <`host`> |string 类型，不需要引号|是|IoTDB 客户端连接 IoTDB 服务器的 IP 地址。|-h 10.129.187.21| -|-help|没有参数|否|打印 IoTDB 的帮助信息|-help| -|-p <`rpcPort`>|int 类型|是|IoTDB 连接服务器的端口号，IoTDB 默认运行在 6667 端口。|-p 6667| -|-pw <`password`>|string 类型，不需要引号|否|IoTDB 连接服务器所使用的密码。如果没有输入密码 IoTDB 会在 Cli 端提示输入密码。|-pw root| -|-u <`username`>|string 类型，不需要引号|是|IoTDB 连接服务器锁使用的用户名。|-u root| -|-maxPRC <`maxPrintRowCount`>|int 类型|否|设置 IoTDB 返回客户端命令行中所显示的最大行数。|-maxPRC 10| -|-e <`execute`> |string 类型|否|在不进入客户端输入模式的情况下，批量操作 IoTDB|-e "show databases"| -|-c | 空 | 否 | 如果服务器设置了 `rpc_thrift_compression_enable=true`, 则 CLI 必须使用 `-c` | -c | - -下面展示一条客户端命令，功能是连接 IP 为 10.129.187.21 的主机，端口为 6667 ，用户名为 root，密码为 root，以数字的形式打印时间戳，IoTDB 命令行显示的最大行数为 10。 - -Linux 系统与 MacOS 系统启动命令如下： - -```shell -Shell > bash sbin/start-cli.sh -h 10.129.187.21 -p 6667 -u root -pw root -disableISO8601 -maxPRC 10 -``` -Windows 系统启动命令如下： - -```shell -# V2.0.4.x 版本之前 -Shell > sbin\start-cli.bat -h 10.129.187.21 -p 6667 -u root -pw root -disableISO8601 -maxPRC 10 - -# V2.0.4.x 版本及之后 -Shell > sbin\windows\start-cli.bat -h 10.129.187.21 -p 6667 -u root -pw root -disableISO8601 -maxPRC 10 -``` - -### 2.3 CLI 特殊命令 -下面列举了一些CLI的特殊命令。 - -| 命令 | 描述 / 例子 | -|:---|:---| -| `set time_display_type=xxx` | 例如： long, default, ISO8601, yyyy-MM-dd HH:mm:ss | -| `show time_display_type` | 显示时间显示方式 | -| `set time_zone=xxx` | 例如： +08:00, Asia/Shanghai | -| `show time_zone` | 显示CLI的时区 | -| `set fetch_size=xxx` | 设置从服务器查询数据时的读取条数 | -| `show fetch_size` | 显示读取条数的大小 | -| `set max_display_num=xxx` | 设置 CLI 一次展示的最大数据条数， 设置为-1表示无限制 | -| `help` | 获取CLI特殊命令的提示 | -| `exit/quit` | 退出CLI | - -### 2.4 使用 OpenID 作为用户名认证登录 - -OpenID Connect (OIDC) 使用 keycloack 作为 OIDC 服务权限认证服务。 - -#### 配置 -配置位于 iotdb-system.properties，设定 authorizer_provider_class 为 org.apache.iotdb.commons.auth.authorizer.OpenIdAuthorizer 则开启了 openID 服务，默认情况下值为 org.apache.iotdb.commons.auth.authorizer.LocalFileAuthorizer 表示没有开启 openID 服务。 - -``` -authorizer_provider_class=org.apache.iotdb.commons.auth.authorizer.OpenIdAuthorizer -``` -如果开启了 openID 服务则 openID_url 为必填项，openID_url 值为 http://ip:port/realms/{realmsName} - -``` -openID_url=http://127.0.0.1:8080/realms/iotdb/ -``` -####keycloack 配置 - -1、下载 keycloack 程序（此教程为21.1.0版本），在 keycloack/bin 中启动 keycloack - -```shell -Shell > cd bin -Shell > ./kc.sh start-dev -``` -2、使用 https://ip:port 登陆 keycloack, 首次登陆需要创建用户 - -![avatar](/img/UserGuide/CLI/Command-Line-Interface/login_keycloak.png?raw=true) - -3、点击 Administration Console 进入管理端 - -![avatar](/img/UserGuide/CLI/Command-Line-Interface/AdministrationConsole.png?raw=true) - -4、在左侧的 Master 菜单点击 Create Realm, 输入 Realm Name 创建一个新的 Realm - -![avatar](/img/UserGuide/CLI/Command-Line-Interface/add_Realm_1.jpg?raw=true) - -![avatar](/img/UserGuide/CLI/Command-Line-Interface/add_Realm_2.jpg?raw=true) - -5、点击左侧菜单 Clients，创建 client - -![avatar](/img/UserGuide/CLI/Command-Line-Interface/client.jpg?raw=true) - -6、点击左侧菜单 User，创建 user - -![avatar](/img/UserGuide/CLI/Command-Line-Interface/user.jpg?raw=true) - -7、点击新创建的用户 id，点击 Credentials 导航输入密码和关闭 Temporary 选项，至此 keyclork 配置完成 - -![avatar](/img/UserGuide/CLI/Command-Line-Interface/pwd.jpg?raw=true) - -8、创建角色，点击左侧菜单的 Roles然后点击Create Role 按钮添加角色 - -![avatar](/img/UserGuide/CLI/Command-Line-Interface/add_role1.jpg?raw=true) - -9、在Role Name 中输入`iotdb_admin`，点击save 按钮。提示：这里的`iotdb_admin`不能为其他名称否则即使登陆成功后也将无权限使用iotdb的查询、插入、创建 database、添加用户、角色等功能 - -![avatar](/img/UserGuide/CLI/Command-Line-Interface/add_role2.jpg?raw=true) - -10、点击左侧的User 菜单然后点击用户列表中的用户为该用户添加我们刚创建的`iotdb_admin`角色 - -![avatar](/img/UserGuide/CLI/Command-Line-Interface/add_role3.jpg?raw=true) - -11、选择Role Mappings ，在Assign role选择`iotdb_admin`增加角色 - -![avatar](/img/UserGuide/CLI/Command-Line-Interface/add_role4.jpg?raw=true) - -![avatar](/img/UserGuide/CLI/Command-Line-Interface/add_role5.jpg?raw=true) - -提示：如果用户角色有调整需要重新生成token并且重新登陆iotdb才会生效 - -以上步骤提供了一种 keycloak 登陆 iotdb 方式，更多方式请参考 keycloak 配置 - -若对应的 IoTDB 服务器开启了使用 OpenID Connect (OIDC) 作为权限认证服务，那么就不再需要使用用户名密码进行登录。 -替而代之的是使用 Token，以及空密码。 -此时，登录命令如下： - -```shell -Shell > bash sbin/start-cli.sh -h 10.129.187.21 -p 6667 -u {my-access-token} -pw "" -``` - -其中，需要将{my-access-token} （注意，包括{}）替换成你的 token，即 access_token 对应的值。密码为空需要再次确认。 - -![avatar](/img/UserGuide/CLI/Command-Line-Interface/iotdbpw.jpeg?raw=true) - -如何获取 token 取决于你的 OIDC 设置。 最简单的一种情况是使用`password-grant`。例如，假设你在用 keycloack 作为你的 OIDC 服务， -并且你在 keycloack 中有一个被定义成 public 的`iotdb`客户的 realm，那么你可以使用如下`curl`命令获得 token。 -（注意例子中的{}和里面的内容需要替换成具体的服务器地址和 realm 名字）： -```shell -curl -X POST "http://{your-keycloack-server}/realms/{your-realm}/protocol/openid-connect/token" \ -H "Content-Type: application/x-www-form-urlencoded" \ - -d "username={username}" \ - -d "password={password}" \ - -d 'grant_type=password' \ - -d "client_id=iotdb-client" -``` - -示例结果如下： - -```json -{"access_token":"eyJhbGciOiJSUzI1NiIsInR5cCIgOiAiSldUIiwia2lkIiA6ICJxMS1XbTBvelE1TzBtUUg4LVNKYXAyWmNONE1tdWNXd25RV0tZeFpKNG93In0.eyJleHAiOjE1OTAzOTgwNzEsImlhdCI6MTU5MDM5Nzc3MSwianRpIjoiNjA0ZmYxMDctN2NiNy00NTRmLWIwYmQtY2M2ZDQwMjFiNGU4IiwiaXNzIjoiaHR0cDovL2F1dGguZGVtby5wcmFnbWF0aWNpbmR1c3RyaWVzLmRlL2F1dGgvcmVhbG1zL0lvVERCIiwiYXVkIjoiYWNjb3VudCIsInN1YiI6ImJhMzJlNDcxLWM3NzItNGIzMy04ZGE2LTZmZThhY2RhMDA3MyIsInR5cCI6IkJlYXJlciIsImF6cCI6ImlvdGRiIiwic2Vzc2lvbl9zdGF0ZSI6IjA2MGQyODYyLTE0ZWQtNDJmZS1iYWY3LThkMWY3ODQ2NTdmMSIsImFjciI6IjEiLCJhbGxvd2VkLW9yaWdpbnMiOlsibG9jYWxob3N0OjgwODAiXSwicmVhbG1fYWNjZXNzIjp7InJvbGVzIjpbIm9mZmxpbmVfYWNjZXNzIiwidW1hX2F1dGhvcml6YXRpb24iLCJpb3RkYl9hZG1pbiJdfSwicmVzb3VyY2VfYWNjZXNzIjp7ImFjY291bnQiOnsicm9sZXMiOlsibWFuYWdlLWFjY291bnQiLCJtYW5hZ2UtYWNjb3VudC1saW5rcyIsInZpZXctcHJvZmlsZSJdfX0sInNjb3BlIjoiZW1haWwgcHJvZmlsZSIsImVtYWlsX3ZlcmlmaWVkIjp0cnVlLCJwcmVmZXJyZWRfdXNlcm5hbWUiOiJ1c2VyIn0.nwbrJkWdCNjzFrTDwKNuV5h9dDMg5ytRKGOXmFIajpfsbOutJytjWTCB2WpA8E1YI3KM6gU6Jx7cd7u0oPo5syHhfCz119n_wBiDnyTZkFOAPsx0M2z20kvBLN9k36_VfuCMFUeddJjO31MeLTmxB0UKg2VkxdczmzMH3pnalhxqpnWWk3GnrRrhAf2sZog0foH4Ae3Ks0lYtYzaWK_Yo7E4Px42-gJpohy3JevOC44aJ4auzJR1RBj9LUbgcRinkBy0JLi6XXiYznSC2V485CSBHW3sseXn7pSXQADhnmGQrLfFGO5ZljmPO18eFJaimdjvgSChsrlSEmTDDsoo5Q","expires_in":300,"refresh_expires_in":1800,"refresh_token":"eyJhbGciOiJIUzI1NiIsInR5cCIgOiAiSldUIiwia2lkIiA6ICJhMzZlMGU0NC02MWNmLTQ5NmMtOGRlZi03NTkwNjQ5MzQzMjEifQ.eyJleHAiOjE1OTAzOTk1NzEsImlhdCI6MTU5MDM5Nzc3MSwianRpIjoiNmMxNTBiY2EtYmE5NC00NTgxLWEwODEtYjI2YzhhMmI5YmZmIiwiaXNzIjoiaHR0cDovL2F1dGguZGVtby5wcmFnbWF0aWNpbmR1c3RyaWVzLmRlL2F1dGgvcmVhbG1zL0lvVERCIiwiYXVkIjoiaHR0cDovL2F1dGguZGVtby5wcmFnbWF0aWNpbmR1c3RyaWVzLmRlL2F1dGgvcmVhbG1zL0lvVERCIiwic3ViIjoiYmEzMmU0NzEtYzc3Mi00YjMzLThkYTYtNmZlOGFjZGEwMDczIiwidHlwIjoiUmVmcmVzaCIsImF6cCI6ImlvdGRiIiwic2Vzc2lvbl9zdGF0ZSI6IjA2MGQyODYyLTE0ZWQtNDJmZS1iYWY3LThkMWY3ODQ2NTdmMSIsInNjb3BlIjoiZW1haWwgcHJvZmlsZSJ9.ayNpXdNX28qahodX1zowrMGiUCw2AodlHBQFqr8Ui7c","token_type":"bearer","not-before-policy":0,"session_state":"060d2862-14ed-42fe-baf7-8d1f784657f1","scope":"email profile"} -``` - -### 2.5 Cli 的批量操作 -当您想要通过脚本的方式通过 Cli / Shell 对 IoTDB 进行批量操作时，可以使用-e 参数。通过使用该参数，您可以在不进入客户端输入模式的情况下操作 IoTDB。 - -为了避免 SQL 语句和其他参数混淆，现在只支持-e 参数作为最后的参数使用。 - -针对 cli/Shell 工具的-e 参数用法如下： - -Linux 系统与 MacOS 指令： - -```shell -Shell > bash sbin/start-cli.sh -h {host} -p {rpcPort} -u {user} -pw {password} -e {sql for iotdb} -``` - -Windows 系统指令 -```shell -# V2.0.4.x 版本之前 -Shell > sbin\start-cli.bat -h {host} -p {rpcPort} -u {user} -pw {password} -e {sql for iotdb} - -# V2.0.4.x 版本及之后 -Shell > sbin\windows\start-cli.bat -h {host} -p {rpcPort} -u {user} -pw {password} -e {sql for iotdb} -``` - -在 Windows 环境下，-e 参数的 SQL 语句需要使用` `` `对于`" "`进行替换 - -为了更好的解释-e 参数的使用，可以参考下面在 Linux 上执行的例子。 - -假设用户希望对一个新启动的 IoTDB 进行如下操作： - -1. 创建名为 root.demo 的 database - -2. 创建名为 root.demo.s1 的时间序列 - -3. 向创建的时间序列中插入三个数据点 - -4. 查询验证数据是否插入成功 - -那么通过使用 cli/Shell 工具的 -e 参数，可以采用如下的脚本： - -```shell -# !/bin/bash - -host=127.0.0.1 -rpcPort=6667 -user=root -pass=root - -bash ./sbin/start-cli.sh -h ${host} -p ${rpcPort} -u ${user} -pw ${pass} -e "CREATE DATABASE root.demo" -bash ./sbin/start-cli.sh -h ${host} -p ${rpcPort} -u ${user} -pw ${pass} -e "create timeseries root.demo.s1 WITH DATATYPE=INT32, ENCODING=RLE" -bash ./sbin/start-cli.sh -h ${host} -p ${rpcPort} -u ${user} -pw ${pass} -e "insert into root.demo(timestamp,s1) values(1,10)" -bash ./sbin/start-cli.sh -h ${host} -p ${rpcPort} -u ${user} -pw ${pass} -e "insert into root.demo(timestamp,s1) values(2,11)" -bash ./sbin/start-cli.sh -h ${host} -p ${rpcPort} -u ${user} -pw ${pass} -e "insert into root.demo(timestamp,s1) values(3,12)" -bash ./sbin/start-cli.sh -h ${host} -p ${rpcPort} -u ${user} -pw ${pass} -e "select s1 from root.demo" -``` - -打印出来的结果显示如下，通过这种方式进行的操作与客户端的输入模式以及通过 JDBC 进行操作结果是一致的。 - -```shell - Shell > bash ./shell.sh -+-----------------------------+------------+ -| Time|root.demo.s1| -+-----------------------------+------------+ -|1970-01-01T08:00:00.001+08:00| 10| -|1970-01-01T08:00:00.002+08:00| 11| -|1970-01-01T08:00:00.003+08:00| 12| -+-----------------------------+------------+ -Total line number = 3 -It costs 0.267s -``` - -需要特别注意的是，在脚本中使用 -e 参数时要对特殊字符进行转义。 - +--> \ No newline at end of file diff --git a/src/zh/UserGuide/latest/Tools-System/CLI_apache.md b/src/zh/UserGuide/latest/Tools-System/CLI_apache.md new file mode 100644 index 000000000..1adf00af4 --- /dev/null +++ b/src/zh/UserGuide/latest/Tools-System/CLI_apache.md @@ -0,0 +1,288 @@ + + +# 命令行工具 + +IOTDB 为用户提供 cli/Shell 工具用于启动客户端和服务端程序。下面介绍每个 cli/Shell 工具的运行方式和相关参数。 +> \$IOTDB\_HOME 表示 IoTDB 的安装目录所在路径。 + +## 1. 安装 +如果使用源码版，可以在 iotdb 的根目录下执行 + +```shell +> mvn clean package -pl cli -am -DskipTests +``` + +在生成完毕之后，IoTDB 的 Cli 工具位于文件夹"cli/target/iotdb-cli-{project.version}"中。 + +如果你下载的是二进制版，那么 Cli 可以在 sbin 文件夹下直接找到。 + +## 2. 运行 + +### 2.1 Cli 运行方式 +安装后的 IoTDB 中有一个默认用户：`root`，默认密码为`root`。用户可以使用该用户尝试运行 IoTDB 客户端以测试服务器是否正常启动。客户端启动脚本为$IOTDB_HOME/sbin 文件夹下的`start-cli`脚本。启动脚本时需要指定运行 IP 和 RPC PORT。以下为服务器在本机启动，且用户未更改运行端口号的示例，默认端口为 6667。若用户尝试连接远程服务器或更改了服务器运行的端口号，请在-h 和-p 项处使用服务器的 IP 和 RPC PORT。
+用户也可以在启动脚本的最前方设置自己的环境变量，如 JAVA_HOME 等。 + +Linux 系统与 MacOS 系统启动命令如下： + +```shell +Shell > bash sbin/start-cli.sh -h 127.0.0.1 -p 6667 -u root -pw root +``` +Windows 系统启动命令如下： + +```shell +# V2.0.4.x 版本之前 +Shell > sbin\start-cli.bat -h 127.0.0.1 -p 6667 -u root -pw root + +# V2.0.4.x 版本及之后 +Shell > sbin\windows\start-cli.bat -h 127.0.0.1 -p 6667 -u root -pw root +``` +回车后即可成功启动客户端。启动后出现如图提示即为启动成功。 + +``` + _____ _________ ______ ______ +|_ _| | _ _ ||_ _ `.|_ _ \ + | | .--.|_/ | | \_| | | `. \ | |_) | + | | / .'`\ \ | | | | | | | __'. + _| |_| \__. | _| |_ _| |_.' /_| |__) | +|_____|'.__.' |_____| |______.'|_______/ version + +Successfully login at 127.0.0.1:6667 +``` +输入`quit`或`exit`可退出 cli 结束本次会话，cli 输出`quit normally`表示退出成功。 + +### 2.2 Cli 运行参数 + +|参数名|参数类型|是否为必需参数| 说明| 例子 | +|:---|:---|:---|:---|:---| +|-disableISO8601 |没有参数 | 否 |如果设置了这个参数，IoTDB 将以数字的形式打印时间戳 (timestamp)。|-disableISO8601| +|-h <`host`> |string 类型，不需要引号|是|IoTDB 客户端连接 IoTDB 服务器的 IP 地址。|-h 10.129.187.21| +|-help|没有参数|否|打印 IoTDB 的帮助信息|-help| +|-p <`rpcPort`>|int 类型|是|IoTDB 连接服务器的端口号，IoTDB 默认运行在 6667 端口。|-p 6667| +|-pw <`password`>|string 类型，不需要引号|否|IoTDB 连接服务器所使用的密码。如果没有输入密码 IoTDB 会在 Cli 端提示输入密码。|-pw root| +|-u <`username`>|string 类型，不需要引号|是|IoTDB 连接服务器锁使用的用户名。|-u root| +|-maxPRC <`maxPrintRowCount`>|int 类型|否|设置 IoTDB 返回客户端命令行中所显示的最大行数。|-maxPRC 10| +|-e <`execute`> |string 类型|否|在不进入客户端输入模式的情况下，批量操作 IoTDB|-e "show databases"| +|-c | 空 | 否 | 如果服务器设置了 `rpc_thrift_compression_enable=true`, 则 CLI 必须使用 `-c` | -c | + +下面展示一条客户端命令，功能是连接 IP 为 10.129.187.21 的主机，端口为 6667 ，用户名为 root，密码为 root，以数字的形式打印时间戳，IoTDB 命令行显示的最大行数为 10。 + +Linux 系统与 MacOS 系统启动命令如下： + +```shell +Shell > bash sbin/start-cli.sh -h 10.129.187.21 -p 6667 -u root -pw root -disableISO8601 -maxPRC 10 +``` +Windows 系统启动命令如下： + +```shell +# V2.0.4.x 版本之前 +Shell > sbin\start-cli.bat -h 10.129.187.21 -p 6667 -u root -pw root -disableISO8601 -maxPRC 10 + +# V2.0.4.x 版本及之后 +Shell > sbin\windows\start-cli.bat -h 10.129.187.21 -p 6667 -u root -pw root -disableISO8601 -maxPRC 10 +``` + +### 2.3 CLI 特殊命令 +下面列举了一些CLI的特殊命令。 + +| 命令 | 描述 / 例子 | +|:---|:---| +| `set time_display_type=xxx` | 例如： long, default, ISO8601, yyyy-MM-dd HH:mm:ss | +| `show time_display_type` | 显示时间显示方式 | +| `set time_zone=xxx` | 例如： +08:00, Asia/Shanghai | +| `show time_zone` | 显示CLI的时区 | +| `set fetch_size=xxx` | 设置从服务器查询数据时的读取条数 | +| `show fetch_size` | 显示读取条数的大小 | +| `set max_display_num=xxx` | 设置 CLI 一次展示的最大数据条数， 设置为-1表示无限制 | +| `help` | 获取CLI特殊命令的提示 | +| `exit/quit` | 退出CLI | + +### 2.4 使用 OpenID 作为用户名认证登录 + +OpenID Connect (OIDC) 使用 keycloack 作为 OIDC 服务权限认证服务。 + +#### 配置 +配置位于 iotdb-system.properties，设定 authorizer_provider_class 为 org.apache.iotdb.commons.auth.authorizer.OpenIdAuthorizer 则开启了 openID 服务，默认情况下值为 org.apache.iotdb.commons.auth.authorizer.LocalFileAuthorizer 表示没有开启 openID 服务。 + +``` +authorizer_provider_class=org.apache.iotdb.commons.auth.authorizer.OpenIdAuthorizer +``` +如果开启了 openID 服务则 openID_url 为必填项，openID_url 值为 http://ip:port/realms/{realmsName} + +``` +openID_url=http://127.0.0.1:8080/realms/iotdb/ +``` +#### keycloack 配置 + +1、下载 keycloack 程序（此教程为21.1.0版本），在 keycloack/bin 中启动 keycloack + +```shell +Shell > cd bin +Shell > ./kc.sh start-dev +``` +2、使用 https://ip:port 登陆 keycloack, 首次登陆需要创建用户 + +![avatar](/img/UserGuide/CLI/Command-Line-Interface/login_keycloak.png?raw=true) + +3、点击 Administration Console 进入管理端 + +![avatar](/img/UserGuide/CLI/Command-Line-Interface/AdministrationConsole.png?raw=true) + +4、在左侧的 Master 菜单点击 Create Realm, 输入 Realm Name 创建一个新的 Realm + +![avatar](/img/UserGuide/CLI/Command-Line-Interface/add_Realm_1.jpg?raw=true) + +![avatar](/img/UserGuide/CLI/Command-Line-Interface/add_Realm_2.jpg?raw=true) + +5、点击左侧菜单 Clients，创建 client + +![avatar](/img/UserGuide/CLI/Command-Line-Interface/client.jpg?raw=true) + +6、点击左侧菜单 User，创建 user + +![avatar](/img/UserGuide/CLI/Command-Line-Interface/user.jpg?raw=true) + +7、点击新创建的用户 id，点击 Credentials 导航输入密码和关闭 Temporary 选项，至此 keyclork 配置完成 + +![avatar](/img/UserGuide/CLI/Command-Line-Interface/pwd.jpg?raw=true) + +8、创建角色，点击左侧菜单的 Roles然后点击Create Role 按钮添加角色 + +![avatar](/img/UserGuide/CLI/Command-Line-Interface/add_role1.jpg?raw=true) + +9、在Role Name 中输入`iotdb_admin`，点击save 按钮。提示：这里的`iotdb_admin`不能为其他名称否则即使登陆成功后也将无权限使用iotdb的查询、插入、创建 database、添加用户、角色等功能 + +![avatar](/img/UserGuide/CLI/Command-Line-Interface/add_role2.jpg?raw=true) + +10、点击左侧的User 菜单然后点击用户列表中的用户为该用户添加我们刚创建的`iotdb_admin`角色 + +![avatar](/img/UserGuide/CLI/Command-Line-Interface/add_role3.jpg?raw=true) + +11、选择Role Mappings ，在Assign role选择`iotdb_admin`增加角色 + +![avatar](/img/UserGuide/CLI/Command-Line-Interface/add_role4.jpg?raw=true) + +![avatar](/img/UserGuide/CLI/Command-Line-Interface/add_role5.jpg?raw=true) + +提示：如果用户角色有调整需要重新生成token并且重新登陆iotdb才会生效 + +以上步骤提供了一种 keycloak 登陆 iotdb 方式，更多方式请参考 keycloak 配置 + +若对应的 IoTDB 服务器开启了使用 OpenID Connect (OIDC) 作为权限认证服务，那么就不再需要使用用户名密码进行登录。 +替而代之的是使用 Token，以及空密码。 +此时，登录命令如下： + +```shell +Shell > bash sbin/start-cli.sh -h 10.129.187.21 -p 6667 -u {my-access-token} -pw "" +``` + +其中，需要将{my-access-token} （注意，包括{}）替换成你的 token，即 access_token 对应的值。密码为空需要再次确认。 + +![avatar](/img/UserGuide/CLI/Command-Line-Interface/iotdbpw.jpeg?raw=true) + +如何获取 token 取决于你的 OIDC 设置。 最简单的一种情况是使用`password-grant`。例如，假设你在用 keycloack 作为你的 OIDC 服务， +并且你在 keycloack 中有一个被定义成 public 的`iotdb`客户的 realm，那么你可以使用如下`curl`命令获得 token。 +（注意例子中的{}和里面的内容需要替换成具体的服务器地址和 realm 名字）： +```shell +curl -X POST "http://{your-keycloack-server}/realms/{your-realm}/protocol/openid-connect/token" \ -H "Content-Type: application/x-www-form-urlencoded" \ + -d "username={username}" \ + -d "password={password}" \ + -d 'grant_type=password' \ + -d "client_id=iotdb-client" +``` + +示例结果如下： + +```json +{"access_token":"eyJhbGciOiJSUzI1NiIsInR5cCIgOiAiSldUIiwia2lkIiA6ICJxMS1XbTBvelE1TzBtUUg4LVNKYXAyWmNONE1tdWNXd25RV0tZeFpKNG93In0.eyJleHAiOjE1OTAzOTgwNzEsImlhdCI6MTU5MDM5Nzc3MSwianRpIjoiNjA0ZmYxMDctN2NiNy00NTRmLWIwYmQtY2M2ZDQwMjFiNGU4IiwiaXNzIjoiaHR0cDovL2F1dGguZGVtby5wcmFnbWF0aWNpbmR1c3RyaWVzLmRlL2F1dGgvcmVhbG1zL0lvVERCIiwiYXVkIjoiYWNjb3VudCIsInN1YiI6ImJhMzJlNDcxLWM3NzItNGIzMy04ZGE2LTZmZThhY2RhMDA3MyIsInR5cCI6IkJlYXJlciIsImF6cCI6ImlvdGRiIiwic2Vzc2lvbl9zdGF0ZSI6IjA2MGQyODYyLTE0ZWQtNDJmZS1iYWY3LThkMWY3ODQ2NTdmMSIsImFjciI6IjEiLCJhbGxvd2VkLW9yaWdpbnMiOlsibG9jYWxob3N0OjgwODAiXSwicmVhbG1fYWNjZXNzIjp7InJvbGVzIjpbIm9mZmxpbmVfYWNjZXNzIiwidW1hX2F1dGhvcml6YXRpb24iLCJpb3RkYl9hZG1pbiJdfSwicmVzb3VyY2VfYWNjZXNzIjp7ImFjY291bnQiOnsicm9sZXMiOlsibWFuYWdlLWFjY291bnQiLCJtYW5hZ2UtYWNjb3VudC1saW5rcyIsInZpZXctcHJvZmlsZSJdfX0sInNjb3BlIjoiZW1haWwgcHJvZmlsZSIsImVtYWlsX3ZlcmlmaWVkIjp0cnVlLCJwcmVmZXJyZWRfdXNlcm5hbWUiOiJ1c2VyIn0.nwbrJkWdCNjzFrTDwKNuV5h9dDMg5ytRKGOXmFIajpfsbOutJytjWTCB2WpA8E1YI3KM6gU6Jx7cd7u0oPo5syHhfCz119n_wBiDnyTZkFOAPsx0M2z20kvBLN9k36_VfuCMFUeddJjO31MeLTmxB0UKg2VkxdczmzMH3pnalhxqpnWWk3GnrRrhAf2sZog0foH4Ae3Ks0lYtYzaWK_Yo7E4Px42-gJpohy3JevOC44aJ4auzJR1RBj9LUbgcRinkBy0JLi6XXiYznSC2V485CSBHW3sseXn7pSXQADhnmGQrLfFGO5ZljmPO18eFJaimdjvgSChsrlSEmTDDsoo5Q","expires_in":300,"refresh_expires_in":1800,"refresh_token":"eyJhbGciOiJIUzI1NiIsInR5cCIgOiAiSldUIiwia2lkIiA6ICJhMzZlMGU0NC02MWNmLTQ5NmMtOGRlZi03NTkwNjQ5MzQzMjEifQ.eyJleHAiOjE1OTAzOTk1NzEsImlhdCI6MTU5MDM5Nzc3MSwianRpIjoiNmMxNTBiY2EtYmE5NC00NTgxLWEwODEtYjI2YzhhMmI5YmZmIiwiaXNzIjoiaHR0cDovL2F1dGguZGVtby5wcmFnbWF0aWNpbmR1c3RyaWVzLmRlL2F1dGgvcmVhbG1zL0lvVERCIiwiYXVkIjoiaHR0cDovL2F1dGguZGVtby5wcmFnbWF0aWNpbmR1c3RyaWVzLmRlL2F1dGgvcmVhbG1zL0lvVERCIiwic3ViIjoiYmEzMmU0NzEtYzc3Mi00YjMzLThkYTYtNmZlOGFjZGEwMDczIiwidHlwIjoiUmVmcmVzaCIsImF6cCI6ImlvdGRiIiwic2Vzc2lvbl9zdGF0ZSI6IjA2MGQyODYyLTE0ZWQtNDJmZS1iYWY3LThkMWY3ODQ2NTdmMSIsInNjb3BlIjoiZW1haWwgcHJvZmlsZSJ9.ayNpXdNX28qahodX1zowrMGiUCw2AodlHBQFqr8Ui7c","token_type":"bearer","not-before-policy":0,"session_state":"060d2862-14ed-42fe-baf7-8d1f784657f1","scope":"email profile"} +``` + +### 2.5 Cli 的批量操作 +当您想要通过脚本的方式通过 Cli / Shell 对 IoTDB 进行批量操作时，可以使用-e 参数。通过使用该参数，您可以在不进入客户端输入模式的情况下操作 IoTDB。 + +为了避免 SQL 语句和其他参数混淆，现在只支持-e 参数作为最后的参数使用。 + +针对 cli/Shell 工具的-e 参数用法如下： + +Linux 系统与 MacOS 指令： + +```shell +Shell > bash sbin/start-cli.sh -h {host} -p {rpcPort} -u {user} -pw {password} -e {sql for iotdb} +``` + +Windows 系统指令 +```shell +# V2.0.4.x 版本之前 +Shell > sbin\start-cli.bat -h {host} -p {rpcPort} -u {user} -pw {password} -e {sql for iotdb} + +# V2.0.4.x 版本及之后 +Shell > sbin\windows\start-cli.bat -h {host} -p {rpcPort} -u {user} -pw {password} -e {sql for iotdb} +``` + +在 Windows 环境下，-e 参数的 SQL 语句需要使用` `` `对于`" "`进行替换 + +为了更好的解释-e 参数的使用，可以参考下面在 Linux 上执行的例子。 + +假设用户希望对一个新启动的 IoTDB 进行如下操作： + +1. 创建名为 root.demo 的 database + +2. 创建名为 root.demo.s1 的时间序列 + +3. 向创建的时间序列中插入三个数据点 + +4. 查询验证数据是否插入成功 + +那么通过使用 cli/Shell 工具的 -e 参数，可以采用如下的脚本： + +```shell +# !/bin/bash + +host=127.0.0.1 +rpcPort=6667 +user=root +pass=root + +bash ./sbin/start-cli.sh -h ${host} -p ${rpcPort} -u ${user} -pw ${pass} -e "CREATE DATABASE root.demo" +bash ./sbin/start-cli.sh -h ${host} -p ${rpcPort} -u ${user} -pw ${pass} -e "create timeseries root.demo.s1 WITH DATATYPE=INT32, ENCODING=RLE" +bash ./sbin/start-cli.sh -h ${host} -p ${rpcPort} -u ${user} -pw ${pass} -e "insert into root.demo(timestamp,s1) values(1,10)" +bash ./sbin/start-cli.sh -h ${host} -p ${rpcPort} -u ${user} -pw ${pass} -e "insert into root.demo(timestamp,s1) values(2,11)" +bash ./sbin/start-cli.sh -h ${host} -p ${rpcPort} -u ${user} -pw ${pass} -e "insert into root.demo(timestamp,s1) values(3,12)" +bash ./sbin/start-cli.sh -h ${host} -p ${rpcPort} -u ${user} -pw ${pass} -e "select s1 from root.demo" +``` + +打印出来的结果显示如下，通过这种方式进行的操作与客户端的输入模式以及通过 JDBC 进行操作结果是一致的。 + +```shell + Shell > bash ./shell.sh ++-----------------------------+------------+ +| Time|root.demo.s1| ++-----------------------------+------------+ +|1970-01-01T08:00:00.001+08:00| 10| +|1970-01-01T08:00:00.002+08:00| 11| +|1970-01-01T08:00:00.003+08:00| 12| ++-----------------------------+------------+ +Total line number = 3 +It costs 0.267s +``` + +需要特别注意的是，在脚本中使用 -e 参数时要对特殊字符进行转义。 + diff --git a/src/zh/UserGuide/latest/Tools-System/CLI_timecho.md b/src/zh/UserGuide/latest/Tools-System/CLI_timecho.md new file mode 100644 index 000000000..c3d9f570f --- /dev/null +++ b/src/zh/UserGuide/latest/Tools-System/CLI_timecho.md @@ -0,0 +1,275 @@ + + +# 命令行工具 + +IOTDB 为用户提供 cli/Shell 工具用于启动客户端和服务端程序。下面介绍每个 cli/Shell 工具的运行方式和相关参数。 +> \$IOTDB\_HOME 表示 IoTDB 的安装目录所在路径。 + +## 1. Cli 运行方式 +安装后的 IoTDB 中有一个默认用户：`root`，默认密码为`root`。用户可以使用该用户尝试运行 IoTDB 客户端以测试服务器是否正常启动。客户端启动脚本为$IOTDB_HOME/sbin 文件夹下的`start-cli`脚本。启动脚本时需要指定运行 IP 和 RPC PORT。以下为服务器在本机启动，且用户未更改运行端口号的示例，默认端口为 6667。若用户尝试连接远程服务器或更改了服务器运行的端口号，请在-h 和-p 项处使用服务器的 IP 和 RPC PORT。
+用户也可以在启动脚本的最前方设置自己的环境变量，如 JAVA_HOME 等。 + +Linux 系统与 MacOS 系统启动命令如下： + +```shell +Shell > bash sbin/start-cli.sh -h 127.0.0.1 -p 6667 -u root -pw root +``` +Windows 系统启动命令如下： + +```shell +# V2.0.4.x 版本之前 +Shell > sbin\start-cli.bat -h 127.0.0.1 -p 6667 -u root -pw root + +# V2.0.4.x 版本及之后 +Shell > sbin\windows\start-cli.bat -h 127.0.0.1 -p 6667 -u root -pw root +``` +回车后即可成功启动客户端。启动后出现如图提示即为启动成功。 + +``` + _____ _________ ______ ______ +|_ _| | _ _ ||_ _ `.|_ _ \ + | | .--.|_/ | | \_| | | `. \ | |_) | + | | / .'`\ \ | | | | | | | __'. + _| |_| \__. | _| |_ _| |_.' /_| |__) | +|_____|'.__.' |_____| |______.'|_______/ version + +Successfully login at 127.0.0.1:6667 +``` +输入`quit`或`exit`可退出 cli 结束本次会话，cli 输出`quit normally`表示退出成功。 + +## 2. Cli 运行参数 + +|参数名|参数类型|是否为必需参数| 说明| 例子 | +|:---|:---|:---|:---|:---| +|-disableISO8601 |没有参数 | 否 |如果设置了这个参数，IoTDB 将以数字的形式打印时间戳 (timestamp)。|-disableISO8601| +|-h <`host`> |string 类型，不需要引号|是|IoTDB 客户端连接 IoTDB 服务器的 IP 地址。|-h 10.129.187.21| +|-help|没有参数|否|打印 IoTDB 的帮助信息|-help| +|-p <`rpcPort`>|int 类型|是|IoTDB 连接服务器的端口号，IoTDB 默认运行在 6667 端口。|-p 6667| +|-pw <`password`>|string 类型，不需要引号|否|IoTDB 连接服务器所使用的密码。如果没有输入密码 IoTDB 会在 Cli 端提示输入密码。|-pw root| +|-u <`username`>|string 类型，不需要引号|是|IoTDB 连接服务器锁使用的用户名。|-u root| +|-maxPRC <`maxPrintRowCount`>|int 类型|否|设置 IoTDB 返回客户端命令行中所显示的最大行数。|-maxPRC 10| +|-e <`execute`> |string 类型|否|在不进入客户端输入模式的情况下，批量操作 IoTDB|-e "show databases"| +|-c | 空 | 否 | 如果服务器设置了 `rpc_thrift_compression_enable=true`, 则 CLI 必须使用 `-c` | -c | + +下面展示一条客户端命令，功能是连接 IP 为 10.129.187.21 的主机，端口为 6667 ，用户名为 root，密码为 root，以数字的形式打印时间戳，IoTDB 命令行显示的最大行数为 10。 + +Linux 系统与 MacOS 系统启动命令如下： + +```shell +Shell > bash sbin/start-cli.sh -h 10.129.187.21 -p 6667 -u root -pw root -disableISO8601 -maxPRC 10 +``` +Windows 系统启动命令如下： + +```shell +# V2.0.4.x 版本之前 +Shell > sbin\start-cli.bat -h 10.129.187.21 -p 6667 -u root -pw root -disableISO8601 -maxPRC 10 + +# V2.0.4.x 版本及之后 +Shell > sbin\windows\start-cli.bat -h 10.129.187.21 -p 6667 -u root -pw root -disableISO8601 -maxPRC 10 +``` + +## 3. CLI 特殊命令 +下面列举了一些CLI的特殊命令。 + +| 命令 | 描述 / 例子 | +|:---|:---| +| `set time_display_type=xxx` | 例如： long, default, ISO8601, yyyy-MM-dd HH:mm:ss | +| `show time_display_type` | 显示时间显示方式 | +| `set time_zone=xxx` | 例如： +08:00, Asia/Shanghai | +| `show time_zone` | 显示CLI的时区 | +| `set fetch_size=xxx` | 设置从服务器查询数据时的读取条数 | +| `show fetch_size` | 显示读取条数的大小 | +| `set max_display_num=xxx` | 设置 CLI 一次展示的最大数据条数， 设置为-1表示无限制 | +| `help` | 获取CLI特殊命令的提示 | +| `exit/quit` | 退出CLI | + +## 4. 使用 OpenID 作为用户名认证登录 + +OpenID Connect (OIDC) 使用 keycloack 作为 OIDC 服务权限认证服务。 + +### 配置 +配置位于 iotdb-system.properties，设定 authorizer_provider_class 为 org.apache.iotdb.commons.auth.authorizer.OpenIdAuthorizer 则开启了 openID 服务，默认情况下值为 org.apache.iotdb.commons.auth.authorizer.LocalFileAuthorizer 表示没有开启 openID 服务。 + +``` +authorizer_provider_class=org.apache.iotdb.commons.auth.authorizer.OpenIdAuthorizer +``` +如果开启了 openID 服务则 openID_url 为必填项，openID_url 值为 http://ip:port/realms/{realmsName} + +``` +openID_url=http://127.0.0.1:8080/realms/iotdb/ +``` +### keycloack 配置 + +1、下载 keycloack 程序（此教程为21.1.0版本），在 keycloack/bin 中启动 keycloack + +```shell +Shell > cd bin +Shell > ./kc.sh start-dev +``` +2、使用 https://ip:port 登陆 keycloack, 首次登陆需要创建用户 + +![avatar](/img/UserGuide/CLI/Command-Line-Interface/login_keycloak.png?raw=true) + +3、点击 Administration Console 进入管理端 + +![avatar](/img/UserGuide/CLI/Command-Line-Interface/AdministrationConsole.png?raw=true) + +4、在左侧的 Master 菜单点击 Create Realm, 输入 Realm Name 创建一个新的 Realm + +![avatar](/img/UserGuide/CLI/Command-Line-Interface/add_Realm_1.jpg?raw=true) + +![avatar](/img/UserGuide/CLI/Command-Line-Interface/add_Realm_2.jpg?raw=true) + +5、点击左侧菜单 Clients，创建 client + +![avatar](/img/UserGuide/CLI/Command-Line-Interface/client.jpg?raw=true) + +6、点击左侧菜单 User，创建 user + +![avatar](/img/UserGuide/CLI/Command-Line-Interface/user.jpg?raw=true) + +7、点击新创建的用户 id，点击 Credentials 导航输入密码和关闭 Temporary 选项，至此 keyclork 配置完成 + +![avatar](/img/UserGuide/CLI/Command-Line-Interface/pwd.jpg?raw=true) + +8、创建角色，点击左侧菜单的 Roles然后点击Create Role 按钮添加角色 + +![avatar](/img/UserGuide/CLI/Command-Line-Interface/add_role1.jpg?raw=true) + +9、在Role Name 中输入`iotdb_admin`，点击save 按钮。提示：这里的`iotdb_admin`不能为其他名称否则即使登陆成功后也将无权限使用iotdb的查询、插入、创建 database、添加用户、角色等功能 + +![avatar](/img/UserGuide/CLI/Command-Line-Interface/add_role2.jpg?raw=true) + +10、点击左侧的User 菜单然后点击用户列表中的用户为该用户添加我们刚创建的`iotdb_admin`角色 + +![avatar](/img/UserGuide/CLI/Command-Line-Interface/add_role3.jpg?raw=true) + +11、选择Role Mappings ，在Assign role选择`iotdb_admin`增加角色 + +![avatar](/img/UserGuide/CLI/Command-Line-Interface/add_role4.jpg?raw=true) + +![avatar](/img/UserGuide/CLI/Command-Line-Interface/add_role5.jpg?raw=true) + +提示：如果用户角色有调整需要重新生成token并且重新登陆iotdb才会生效 + +以上步骤提供了一种 keycloak 登陆 iotdb 方式，更多方式请参考 keycloak 配置 + +若对应的 IoTDB 服务器开启了使用 OpenID Connect (OIDC) 作为权限认证服务，那么就不再需要使用用户名密码进行登录。 +替而代之的是使用 Token，以及空密码。 +此时，登录命令如下： + +```shell +Shell > bash sbin/start-cli.sh -h 10.129.187.21 -p 6667 -u {my-access-token} -pw "" +``` + +其中，需要将{my-access-token} （注意，包括{}）替换成你的 token，即 access_token 对应的值。密码为空需要再次确认。 + +![avatar](/img/UserGuide/CLI/Command-Line-Interface/iotdbpw.jpeg?raw=true) + +如何获取 token 取决于你的 OIDC 设置。 最简单的一种情况是使用`password-grant`。例如，假设你在用 keycloack 作为你的 OIDC 服务， +并且你在 keycloack 中有一个被定义成 public 的`iotdb`客户的 realm，那么你可以使用如下`curl`命令获得 token。 +（注意例子中的{}和里面的内容需要替换成具体的服务器地址和 realm 名字）： +```shell +curl -X POST "http://{your-keycloack-server}/realms/{your-realm}/protocol/openid-connect/token" \ -H "Content-Type: application/x-www-form-urlencoded" \ + -d "username={username}" \ + -d "password={password}" \ + -d 'grant_type=password' \ + -d "client_id=iotdb-client" +``` + +示例结果如下： + +```json +{"access_token":"eyJhbGciOiJSUzI1NiIsInR5cCIgOiAiSldUIiwia2lkIiA6ICJxMS1XbTBvelE1TzBtUUg4LVNKYXAyWmNONE1tdWNXd25RV0tZeFpKNG93In0.eyJleHAiOjE1OTAzOTgwNzEsImlhdCI6MTU5MDM5Nzc3MSwianRpIjoiNjA0ZmYxMDctN2NiNy00NTRmLWIwYmQtY2M2ZDQwMjFiNGU4IiwiaXNzIjoiaHR0cDovL2F1dGguZGVtby5wcmFnbWF0aWNpbmR1c3RyaWVzLmRlL2F1dGgvcmVhbG1zL0lvVERCIiwiYXVkIjoiYWNjb3VudCIsInN1YiI6ImJhMzJlNDcxLWM3NzItNGIzMy04ZGE2LTZmZThhY2RhMDA3MyIsInR5cCI6IkJlYXJlciIsImF6cCI6ImlvdGRiIiwic2Vzc2lvbl9zdGF0ZSI6IjA2MGQyODYyLTE0ZWQtNDJmZS1iYWY3LThkMWY3ODQ2NTdmMSIsImFjciI6IjEiLCJhbGxvd2VkLW9yaWdpbnMiOlsibG9jYWxob3N0OjgwODAiXSwicmVhbG1fYWNjZXNzIjp7InJvbGVzIjpbIm9mZmxpbmVfYWNjZXNzIiwidW1hX2F1dGhvcml6YXRpb24iLCJpb3RkYl9hZG1pbiJdfSwicmVzb3VyY2VfYWNjZXNzIjp7ImFjY291bnQiOnsicm9sZXMiOlsibWFuYWdlLWFjY291bnQiLCJtYW5hZ2UtYWNjb3VudC1saW5rcyIsInZpZXctcHJvZmlsZSJdfX0sInNjb3BlIjoiZW1haWwgcHJvZmlsZSIsImVtYWlsX3ZlcmlmaWVkIjp0cnVlLCJwcmVmZXJyZWRfdXNlcm5hbWUiOiJ1c2VyIn0.nwbrJkWdCNjzFrTDwKNuV5h9dDMg5ytRKGOXmFIajpfsbOutJytjWTCB2WpA8E1YI3KM6gU6Jx7cd7u0oPo5syHhfCz119n_wBiDnyTZkFOAPsx0M2z20kvBLN9k36_VfuCMFUeddJjO31MeLTmxB0UKg2VkxdczmzMH3pnalhxqpnWWk3GnrRrhAf2sZog0foH4Ae3Ks0lYtYzaWK_Yo7E4Px42-gJpohy3JevOC44aJ4auzJR1RBj9LUbgcRinkBy0JLi6XXiYznSC2V485CSBHW3sseXn7pSXQADhnmGQrLfFGO5ZljmPO18eFJaimdjvgSChsrlSEmTDDsoo5Q","expires_in":300,"refresh_expires_in":1800,"refresh_token":"eyJhbGciOiJIUzI1NiIsInR5cCIgOiAiSldUIiwia2lkIiA6ICJhMzZlMGU0NC02MWNmLTQ5NmMtOGRlZi03NTkwNjQ5MzQzMjEifQ.eyJleHAiOjE1OTAzOTk1NzEsImlhdCI6MTU5MDM5Nzc3MSwianRpIjoiNmMxNTBiY2EtYmE5NC00NTgxLWEwODEtYjI2YzhhMmI5YmZmIiwiaXNzIjoiaHR0cDovL2F1dGguZGVtby5wcmFnbWF0aWNpbmR1c3RyaWVzLmRlL2F1dGgvcmVhbG1zL0lvVERCIiwiYXVkIjoiaHR0cDovL2F1dGguZGVtby5wcmFnbWF0aWNpbmR1c3RyaWVzLmRlL2F1dGgvcmVhbG1zL0lvVERCIiwic3ViIjoiYmEzMmU0NzEtYzc3Mi00YjMzLThkYTYtNmZlOGFjZGEwMDczIiwidHlwIjoiUmVmcmVzaCIsImF6cCI6ImlvdGRiIiwic2Vzc2lvbl9zdGF0ZSI6IjA2MGQyODYyLTE0ZWQtNDJmZS1iYWY3LThkMWY3ODQ2NTdmMSIsInNjb3BlIjoiZW1haWwgcHJvZmlsZSJ9.ayNpXdNX28qahodX1zowrMGiUCw2AodlHBQFqr8Ui7c","token_type":"bearer","not-before-policy":0,"session_state":"060d2862-14ed-42fe-baf7-8d1f784657f1","scope":"email profile"} +``` + +## 5. Cli 的批量操作 +当您想要通过脚本的方式通过 Cli / Shell 对 IoTDB 进行批量操作时，可以使用-e 参数。通过使用该参数，您可以在不进入客户端输入模式的情况下操作 IoTDB。 + +为了避免 SQL 语句和其他参数混淆，现在只支持-e 参数作为最后的参数使用。 + +针对 cli/Shell 工具的-e 参数用法如下： + +Linux 系统与 MacOS 指令： + +```shell +Shell > bash sbin/start-cli.sh -h {host} -p {rpcPort} -u {user} -pw {password} -e {sql for iotdb} +``` + +Windows 系统指令 +```shell +# V2.0.4.x 版本之前 +Shell > sbin\start-cli.bat -h {host} -p {rpcPort} -u {user} -pw {password} -e {sql for iotdb} + +# V2.0.4.x 版本及之后 +Shell > sbin\windows\start-cli.bat -h {host} -p {rpcPort} -u {user} -pw {password} -e {sql for iotdb} +``` + +在 Windows 环境下，-e 参数的 SQL 语句需要使用` `` `对于`" "`进行替换 + +为了更好的解释-e 参数的使用，可以参考下面在 Linux 上执行的例子。 + +假设用户希望对一个新启动的 IoTDB 进行如下操作： + +1. 创建名为 root.demo 的 database + +2. 创建名为 root.demo.s1 的时间序列 + +3. 向创建的时间序列中插入三个数据点 + +4. 查询验证数据是否插入成功 + +那么通过使用 cli/Shell 工具的 -e 参数，可以采用如下的脚本： + +```shell +# !/bin/bash + +host=127.0.0.1 +rpcPort=6667 +user=root +pass=root + +bash ./sbin/start-cli.sh -h ${host} -p ${rpcPort} -u ${user} -pw ${pass} -e "CREATE DATABASE root.demo" +bash ./sbin/start-cli.sh -h ${host} -p ${rpcPort} -u ${user} -pw ${pass} -e "create timeseries root.demo.s1 WITH DATATYPE=INT32, ENCODING=RLE" +bash ./sbin/start-cli.sh -h ${host} -p ${rpcPort} -u ${user} -pw ${pass} -e "insert into root.demo(timestamp,s1) values(1,10)" +bash ./sbin/start-cli.sh -h ${host} -p ${rpcPort} -u ${user} -pw ${pass} -e "insert into root.demo(timestamp,s1) values(2,11)" +bash ./sbin/start-cli.sh -h ${host} -p ${rpcPort} -u ${user} -pw ${pass} -e "insert into root.demo(timestamp,s1) values(3,12)" +bash ./sbin/start-cli.sh -h ${host} -p ${rpcPort} -u ${user} -pw ${pass} -e "select s1 from root.demo" +``` + +打印出来的结果显示如下，通过这种方式进行的操作与客户端的输入模式以及通过 JDBC 进行操作结果是一致的。 + +```shell + Shell > bash ./shell.sh ++-----------------------------+------------+ +| Time|root.demo.s1| ++-----------------------------+------------+ +|1970-01-01T08:00:00.001+08:00| 10| +|1970-01-01T08:00:00.002+08:00| 11| +|1970-01-01T08:00:00.003+08:00| 12| ++-----------------------------+------------+ +Total line number = 3 +It costs 0.267s +``` + +需要特别注意的是，在脚本中使用 -e 参数时要对特殊字符进行转义。 +