|
| 1 | +<!-- |
| 2 | +
|
| 3 | + Licensed to the Apache Software Foundation (ASF) under one |
| 4 | + or more contributor license agreements. See the NOTICE file |
| 5 | + distributed with this work for additional information |
| 6 | + regarding copyright ownership. The ASF licenses this file |
| 7 | + to you under the Apache License, Version 2.0 (the |
| 8 | + "License"); you may not use this file except in compliance |
| 9 | + with the License. You may obtain a copy of the License at |
| 10 | + |
| 11 | + http://www.apache.org/licenses/LICENSE-2.0 |
| 12 | + |
| 13 | + Unless required by applicable law or agreed to in writing, |
| 14 | + software distributed under the License is distributed on an |
| 15 | + "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY |
| 16 | + KIND, either express or implied. See the License for the |
| 17 | + specific language governing permissions and limitations |
| 18 | + under the License. |
| 19 | +
|
| 20 | +--> |
| 21 | + |
| 22 | +# Command Line Interface (CLI) |
| 23 | + |
| 24 | + |
| 25 | +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. |
| 26 | + |
| 27 | +> Note: In this document, \$IOTDB\_HOME represents the path of the IoTDB installation directory. |
| 28 | +
|
| 29 | +## Running Cli |
| 30 | + |
| 31 | +After installation, there is a default user in IoTDB: `root`, and the |
| 32 | +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.) |
| 33 | + |
| 34 | +Here is an example where the cluster is started locally and the user has not changed the running port. The default rpc port is |
| 35 | +6667 <br> |
| 36 | +If you need to connect to the remote DataNode or changes |
| 37 | +the rpc port number of the DataNode running, set the specific IP and RPC PORT at -h and -p.<br> |
| 38 | +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) |
| 39 | + |
| 40 | +The Linux and MacOS system startup commands are as follows: |
| 41 | + |
| 42 | +```shell |
| 43 | +Shell > bash sbin/start-cli.sh -h 127.0.0.1 -p 6667 -u root -pw root |
| 44 | +``` |
| 45 | + |
| 46 | +The Windows system startup commands are as follows: |
| 47 | + |
| 48 | +```shell |
| 49 | +Shell > sbin\start-cli.bat -h 127.0.0.1 -p 6667 -u root -pw root |
| 50 | +``` |
| 51 | + |
| 52 | +After operating these commands, the cli can be started successfully. The successful status will be as follows: |
| 53 | + |
| 54 | +``` |
| 55 | + _____ _________ ______ ______ |
| 56 | +|_ _| | _ _ ||_ _ `.|_ _ \ |
| 57 | + | | .--.|_/ | | \_| | | `. \ | |_) | |
| 58 | + | | / .'`\ \ | | | | | | | __'. |
| 59 | + _| |_| \__. | _| |_ _| |_.' /_| |__) | |
| 60 | +|_____|'.__.' |_____| |______.'|_______/ version <version> |
| 61 | +
|
| 62 | +
|
| 63 | +Successfully login at 127.0.0.1:6667 |
| 64 | +IoTDB> |
| 65 | +``` |
| 66 | + |
| 67 | +Enter ```quit``` or `exit` can exit Cli. |
| 68 | + |
| 69 | +## Cli Parameters |
| 70 | + |
| 71 | +| Parameter name | Parameter type | Required | Description | Example | |
| 72 | +| :--------------------------- | :------------------------- | :------- | :----------------------------------------------------------- | :------------------ | |
| 73 | +| -disableISO8601 | No parameters | No | If this parameter is set, IoTDB will print the timestamp in digital form | -disableISO8601 | |
| 74 | +| -h <`host`> | string, no quotation marks | Yes | The IP address of the IoTDB server | -h 10.129.187.21 | |
| 75 | +| -help | No parameters | No | Print help information for IoTDB | -help | |
| 76 | +| -p <`rpcPort`> | int | Yes | The rpc port number of the IoTDB server. IoTDB runs on rpc port 6667 by default | -p 6667 | |
| 77 | +| -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 | |
| 78 | +| -u <`username`> | string, no quotation marks | Yes | User name used for IoTDB to connect the server | -u root | |
| 79 | +| -maxPRC <`maxPrintRowCount`> | int | No | Set the maximum number of rows that IoTDB returns | -maxPRC 10 | |
| 80 | +| -e <`execute`> | string | No | manipulate IoTDB in batches without entering cli input mode | -e "show databases" | |
| 81 | +| -c | empty | No | If the server enables `rpc_thrift_compression_enable=true`, then cli must use `-c` | -c | |
| 82 | + |
| 83 | +Following is a cli command which connects the host with IP |
| 84 | +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. |
| 85 | + |
| 86 | +The Linux and MacOS system startup commands are as follows: |
| 87 | + |
| 88 | +```shell |
| 89 | +Shell > bash sbin/start-cli.sh -h 10.129.187.21 -p 6667 -u root -pw root -disableISO8601 -maxPRC 10 |
| 90 | +``` |
| 91 | + |
| 92 | +The Windows system startup commands are as follows: |
| 93 | + |
| 94 | +```shell |
| 95 | +Shell > sbin\start-cli.bat -h 10.129.187.21 -p 6667 -u root -pw root -disableISO8601 -maxPRC 10 |
| 96 | +``` |
| 97 | + |
| 98 | +## CLI Special Command |
| 99 | + |
| 100 | +Special commands of Cli are below. |
| 101 | + |
| 102 | +| Command | Description / Example | |
| 103 | +| :-------------------------- | :------------------------------------------------------ | |
| 104 | +| `set time_display_type=xxx` | eg. long, default, ISO8601, yyyy-MM-dd HH:mm:ss | |
| 105 | +| `show time_display_type` | show time display type | |
| 106 | +| `set time_zone=xxx` | eg. +08:00, Asia/Shanghai | |
| 107 | +| `show time_zone` | show cli time zone | |
| 108 | +| `set fetch_size=xxx` | set fetch size when querying data from server | |
| 109 | +| `show fetch_size` | show fetch size | |
| 110 | +| `set max_display_num=xxx` | set max lines for cli to output, -1 equals to unlimited | |
| 111 | +| `help` | Get hints for CLI special commands | |
| 112 | +| `exit/quit` | Exit CLI | |
| 113 | + |
| 114 | +## Note on using the CLI with OpenID Connect Auth enabled on Server side |
| 115 | + |
| 116 | +Openid connect (oidc) uses keycloack as the authority authentication service of oidc service |
| 117 | + |
| 118 | + |
| 119 | +### configuration |
| 120 | + |
| 121 | +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. |
| 122 | + |
| 123 | +``` |
| 124 | +authorizer_provider_class=org.apache.iotdb.commons.auth.authorizer.OpenIdAuthorizer |
| 125 | +``` |
| 126 | + |
| 127 | +If the openid service is turned on, openid_URL is required,openID_url value is http://ip:port/realms/{realmsName} |
| 128 | + |
| 129 | +``` |
| 130 | +openID_url=http://127.0.0.1:8080/realms/iotdb/ |
| 131 | +``` |
| 132 | + |
| 133 | +### keycloack configuration |
| 134 | + |
| 135 | +1、Download the keycloack file (This tutorial is version 21.1.0) and start keycloack in keycloack/bin |
| 136 | + |
| 137 | +```shell |
| 138 | +Shell >cd bin |
| 139 | +Shell >./kc.sh start-dev |
| 140 | +``` |
| 141 | + |
| 142 | +2、use url(https://ip:port) login keycloack, the first login needs to create a user |
| 143 | + |
| 144 | + |
| 145 | +3、Click administration console |
| 146 | + |
| 147 | + |
| 148 | +4、In the master menu on the left, click Create realm and enter Realm name to create a new realm |
| 149 | + |
| 150 | + |
| 151 | + |
| 152 | + |
| 153 | + |
| 154 | +5、Click the menu clients on the left to create clients |
| 155 | + |
| 156 | + |
| 157 | + |
| 158 | +6、Click user on the left menu to create user |
| 159 | + |
| 160 | + |
| 161 | + |
| 162 | +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 |
| 163 | + |
| 164 | + |
| 165 | + |
| 166 | +8、To create a role, click Roles on the left menu and then click the Create Role button to add a role |
| 167 | + |
| 168 | + |
| 169 | + |
| 170 | +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 |
| 171 | + |
| 172 | + |
| 173 | + |
| 174 | +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 |
| 175 | + |
| 176 | + |
| 177 | + |
| 178 | +11、 Select Role Mappings, select the `iotdb_admin` role in Assign Role |
| 179 | + |
| 180 | + |
| 181 | + |
| 182 | + |
| 183 | + |
| 184 | + |
| 185 | +Tip: If the user role is adjusted, you need to regenerate the token and log in to iotdb again to take effect |
| 186 | + |
| 187 | +The above steps provide a way for keycloak to log into iotdb. For more ways, please refer to keycloak configuration |
| 188 | + |
| 189 | +If OIDC is enabled on server side then no username / passwort is needed but a valid Access Token from the OIDC Provider. |
| 190 | +So as username you use the token and the password has to be empty, e.g. |
| 191 | + |
| 192 | +```shell |
| 193 | +Shell > bash sbin/start-cli.sh -h 10.129.187.21 -p 6667 -u {my-access-token} -pw "" |
| 194 | +``` |
| 195 | + |
| 196 | +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. |
| 197 | + |
| 198 | + |
| 199 | + |
| 200 | + |
| 201 | +How to get the token is dependent on your OpenID Connect setup and not covered here. |
| 202 | +In the simplest case you can get this via the command line with the `passwort-grant`. |
| 203 | +For example, if you use keycloack as OIDC and you have a realm with a client `iotdb` defined as public you could use |
| 204 | +the following `curl` command to fetch a token (replace all `{}` with appropriate values). |
| 205 | + |
| 206 | +```shell |
| 207 | +curl -X POST "https://{your-keycloack-server}/realms/{your-realm}/protocol/openid-connect/token" \ |
| 208 | + -H "Content-Type: application/x-www-form-urlencoded" \ |
| 209 | + -d "username={username}" \ |
| 210 | + -d "password={password}" \ |
| 211 | + -d 'grant_type=password' \ |
| 212 | + -d "client_id=iotdb-client" |
| 213 | +``` |
| 214 | + |
| 215 | +The response looks something like |
| 216 | + |
| 217 | +```json |
| 218 | +{"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"} |
| 219 | +``` |
| 220 | + |
| 221 | +The interesting part here is the access token with the key `access_token`. |
| 222 | +This has to be passed as username (with parameter `-u`) and empty password to the CLI. |
| 223 | + |
| 224 | +## Batch Operation of Cli |
| 225 | + |
| 226 | +-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. |
| 227 | + |
| 228 | +In order to avoid confusion between statements and other parameters, the current version only supports the -e parameter as the last parameter. |
| 229 | + |
| 230 | +The usage of -e parameter for Cli/shell is as follows: |
| 231 | + |
| 232 | +The Linux and MacOS system commands: |
| 233 | + |
| 234 | +```shell |
| 235 | +Shell > bash sbin/start-cli.sh -h {host} -p {rpcPort} -u {user} -pw {password} -e {sql for iotdb} |
| 236 | +``` |
| 237 | + |
| 238 | +The Windows system commands: |
| 239 | + |
| 240 | +```shell |
| 241 | +Shell > sbin\start-cli.bat -h {host} -p {rpcPort} -u {user} -pw {password} -e {sql for iotdb} |
| 242 | +``` |
| 243 | + |
| 244 | +In the Windows environment, the SQL statement of the -e parameter needs to use ` `` ` to replace `" "` |
| 245 | + |
| 246 | +In order to better explain the use of -e parameter, take following as an example(On linux system). |
| 247 | + |
| 248 | +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: |
| 249 | + |
| 250 | +```shell |
| 251 | +# !/bin/bash |
| 252 | + |
| 253 | +host=127.0.0.1 |
| 254 | +rpcPort=6667 |
| 255 | +user=root |
| 256 | +pass=root |
| 257 | + |
| 258 | +bash ./sbin/start-cli.sh -h ${host} -p ${rpcPort} -u ${user} -pw ${pass} -e "create database root.demo" |
| 259 | +bash ./sbin/start-cli.sh -h ${host} -p ${rpcPort} -u ${user} -pw ${pass} -e "create timeseries root.demo.s1 WITH DATATYPE=INT32, ENCODING=RLE" |
| 260 | +bash ./sbin/start-cli.sh -h ${host} -p ${rpcPort} -u ${user} -pw ${pass} -e "insert into root.demo(timestamp,s1) values(1,10)" |
| 261 | +bash ./sbin/start-cli.sh -h ${host} -p ${rpcPort} -u ${user} -pw ${pass} -e "insert into root.demo(timestamp,s1) values(2,11)" |
| 262 | +bash ./sbin/start-cli.sh -h ${host} -p ${rpcPort} -u ${user} -pw ${pass} -e "insert into root.demo(timestamp,s1) values(3,12)" |
| 263 | +bash ./sbin/start-cli.sh -h ${host} -p ${rpcPort} -u ${user} -pw ${pass} -e "select s1 from root.demo" |
| 264 | +``` |
| 265 | + |
| 266 | +The results are shown in the figure, which are consistent with the Cli and jdbc operations. |
| 267 | + |
| 268 | +```shell |
| 269 | + Shell > bash ./shell.sh |
| 270 | ++-----------------------------+------------+ |
| 271 | +| Time|root.demo.s1| |
| 272 | ++-----------------------------+------------+ |
| 273 | +|1970-01-01T08:00:00.001+08:00| 10| |
| 274 | +|1970-01-01T08:00:00.002+08:00| 11| |
| 275 | +|1970-01-01T08:00:00.003+08:00| 12| |
| 276 | ++-----------------------------+------------+ |
| 277 | +Total line number = 3 |
| 278 | +It costs 0.267s |
| 279 | +``` |
| 280 | + |
| 281 | +It should be noted that the use of the -e parameter in shell scripts requires attention to the escaping of special characters. |
0 commit comments