|
| 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 | +# 命令行工具 |
| 23 | + |
| 24 | +IOTDB 为用户提供 cli/Shell 工具用于启动客户端和服务端程序。下面介绍每个 cli/Shell 工具的运行方式和相关参数。 |
| 25 | +> \$IOTDB\_HOME 表示 IoTDB 的安装目录所在路径。 |
| 26 | +
|
| 27 | +## 1. Cli 运行方式 |
| 28 | +安装后的 IoTDB 中有一个默认用户：`root`，默认密码为`root`。用户可以使用该用户尝试运行 IoTDB 客户端以测试服务器是否正常启动。客户端启动脚本为$IOTDB_HOME/sbin 文件夹下的`start-cli`脚本。启动脚本时需要指定运行 IP 和 RPC PORT。以下为服务器在本机启动，且用户未更改运行端口号的示例，默认端口为 6667。若用户尝试连接远程服务器或更改了服务器运行的端口号，请在-h 和-p 项处使用服务器的 IP 和 RPC PORT。<br> |
| 29 | +用户也可以在启动脚本的最前方设置自己的环境变量，如 JAVA_HOME 等。 |
| 30 | + |
| 31 | +Linux 系统与 MacOS 系统启动命令如下： |
| 32 | + |
| 33 | +```shell |
| 34 | +Shell > bash sbin/start-cli.sh -h 127.0.0.1 -p 6667 -u root -pw root |
| 35 | +``` |
| 36 | +Windows 系统启动命令如下： |
| 37 | + |
| 38 | +```shell |
| 39 | +# V2.0.4.x 版本之前 |
| 40 | +Shell > sbin\start-cli.bat -h 127.0.0.1 -p 6667 -u root -pw root |
| 41 | + |
| 42 | +# V2.0.4.x 版本及之后 |
| 43 | +Shell > sbin\windows\start-cli.bat -h 127.0.0.1 -p 6667 -u root -pw root |
| 44 | +``` |
| 45 | +回车后即可成功启动客户端。启动后出现如图提示即为启动成功。 |
| 46 | + |
| 47 | +``` |
| 48 | + _____ _________ ______ ______ |
| 49 | +|_ _| | _ _ ||_ _ `.|_ _ \ |
| 50 | + | | .--.|_/ | | \_| | | `. \ | |_) | |
| 51 | + | | / .'`\ \ | | | | | | | __'. |
| 52 | + _| |_| \__. | _| |_ _| |_.' /_| |__) | |
| 53 | +|_____|'.__.' |_____| |______.'|_______/ version <version> |
| 54 | +
|
| 55 | +Successfully login at 127.0.0.1:6667 |
| 56 | +``` |
| 57 | +输入`quit`或`exit`可退出 cli 结束本次会话，cli 输出`quit normally`表示退出成功。 |
| 58 | + |
| 59 | +## 2. Cli 运行参数 |
| 60 | + |
| 61 | +|参数名|参数类型|是否为必需参数| 说明| 例子 | |
| 62 | +|:---|:---|:---|:---|:---| |
| 63 | +|-disableISO8601 |没有参数 | 否 |如果设置了这个参数，IoTDB 将以数字的形式打印时间戳 (timestamp)。|-disableISO8601| |
| 64 | +|-h <`host`> |string 类型，不需要引号|是|IoTDB 客户端连接 IoTDB 服务器的 IP 地址。|-h 10.129.187.21| |
| 65 | +|-help|没有参数|否|打印 IoTDB 的帮助信息|-help| |
| 66 | +|-p <`rpcPort`>|int 类型|是|IoTDB 连接服务器的端口号，IoTDB 默认运行在 6667 端口。|-p 6667| |
| 67 | +|-pw <`password`>|string 类型，不需要引号|否|IoTDB 连接服务器所使用的密码。如果没有输入密码 IoTDB 会在 Cli 端提示输入密码。|-pw root| |
| 68 | +|-u <`username`>|string 类型，不需要引号|是|IoTDB 连接服务器锁使用的用户名。|-u root| |
| 69 | +|-maxPRC <`maxPrintRowCount`>|int 类型|否|设置 IoTDB 返回客户端命令行中所显示的最大行数。|-maxPRC 10| |
| 70 | +|-e <`execute`> |string 类型|否|在不进入客户端输入模式的情况下，批量操作 IoTDB|-e "show databases"| |
| 71 | +|-c | 空 | 否 | 如果服务器设置了 `rpc_thrift_compression_enable=true`, 则 CLI 必须使用 `-c` | -c | |
| 72 | + |
| 73 | +下面展示一条客户端命令，功能是连接 IP 为 10.129.187.21 的主机，端口为 6667 ，用户名为 root，密码为 root，以数字的形式打印时间戳，IoTDB 命令行显示的最大行数为 10。 |
| 74 | + |
| 75 | +Linux 系统与 MacOS 系统启动命令如下： |
| 76 | + |
| 77 | +```shell |
| 78 | +Shell > bash sbin/start-cli.sh -h 10.129.187.21 -p 6667 -u root -pw root -disableISO8601 -maxPRC 10 |
| 79 | +``` |
| 80 | +Windows 系统启动命令如下： |
| 81 | + |
| 82 | +```shell |
| 83 | +# V2.0.4.x 版本之前 |
| 84 | +Shell > sbin\start-cli.bat -h 10.129.187.21 -p 6667 -u root -pw root -disableISO8601 -maxPRC 10 |
| 85 | + |
| 86 | +# V2.0.4.x 版本及之后 |
| 87 | +Shell > sbin\windows\start-cli.bat -h 10.129.187.21 -p 6667 -u root -pw root -disableISO8601 -maxPRC 10 |
| 88 | +``` |
| 89 | + |
| 90 | +## 3. CLI 特殊命令 |
| 91 | +下面列举了一些CLI的特殊命令。 |
| 92 | + |
| 93 | +| 命令 | 描述 / 例子 | |
| 94 | +|:---|:---| |
| 95 | +| `set time_display_type=xxx` | 例如： long, default, ISO8601, yyyy-MM-dd HH:mm:ss | |
| 96 | +| `show time_display_type` | 显示时间显示方式 | |
| 97 | +| `set time_zone=xxx` | 例如： +08:00, Asia/Shanghai | |
| 98 | +| `show time_zone` | 显示CLI的时区 | |
| 99 | +| `set fetch_size=xxx` | 设置从服务器查询数据时的读取条数 | |
| 100 | +| `show fetch_size` | 显示读取条数的大小 | |
| 101 | +| `set max_display_num=xxx` | 设置 CLI 一次展示的最大数据条数， 设置为-1表示无限制 | |
| 102 | +| `help` | 获取CLI特殊命令的提示 | |
| 103 | +| `exit/quit` | 退出CLI | |
| 104 | + |
| 105 | +## 4. 使用 OpenID 作为用户名认证登录 |
| 106 | + |
| 107 | +OpenID Connect (OIDC) 使用 keycloack 作为 OIDC 服务权限认证服务。 |
| 108 | + |
| 109 | +#### 配置 |
| 110 | +配置位于 iotdb-system.properties，设定 authorizer_provider_class 为 org.apache.iotdb.commons.auth.authorizer.OpenIdAuthorizer 则开启了 openID 服务，默认情况下值为 org.apache.iotdb.commons.auth.authorizer.LocalFileAuthorizer 表示没有开启 openID 服务。 |
| 111 | + |
| 112 | +``` |
| 113 | +authorizer_provider_class=org.apache.iotdb.commons.auth.authorizer.OpenIdAuthorizer |
| 114 | +``` |
| 115 | +如果开启了 openID 服务则 openID_url 为必填项，openID_url 值为 http://ip:port/realms/{realmsName} |
| 116 | + |
| 117 | +``` |
| 118 | +openID_url=http://127.0.0.1:8080/realms/iotdb/ |
| 119 | +``` |
| 120 | +####keycloack 配置 |
| 121 | + |
| 122 | +1、下载 keycloack 程序（此教程为21.1.0版本），在 keycloack/bin 中启动 keycloack |
| 123 | + |
| 124 | +```shell |
| 125 | +Shell > cd bin |
| 126 | +Shell > ./kc.sh start-dev |
| 127 | +``` |
| 128 | +2、使用 https://ip:port 登陆 keycloack, 首次登陆需要创建用户 |
| 129 | + |
| 130 | + |
| 131 | + |
| 132 | +3、点击 Administration Console 进入管理端 |
| 133 | + |
| 134 | + |
| 135 | + |
| 136 | +4、在左侧的 Master 菜单点击 Create Realm, 输入 Realm Name 创建一个新的 Realm |
| 137 | + |
| 138 | + |
| 139 | + |
| 140 | + |
| 141 | + |
| 142 | +5、点击左侧菜单 Clients，创建 client |
| 143 | + |
| 144 | + |
| 145 | + |
| 146 | +6、点击左侧菜单 User，创建 user |
| 147 | + |
| 148 | + |
| 149 | + |
| 150 | +7、点击新创建的用户 id，点击 Credentials 导航输入密码和关闭 Temporary 选项，至此 keyclork 配置完成 |
| 151 | + |
| 152 | + |
| 153 | + |
| 154 | +8、创建角色，点击左侧菜单的 Roles然后点击Create Role 按钮添加角色 |
| 155 | + |
| 156 | + |
| 157 | + |
| 158 | +9、在Role Name 中输入`iotdb_admin`，点击save 按钮。提示：这里的`iotdb_admin`不能为其他名称否则即使登陆成功后也将无权限使用iotdb的查询、插入、创建 database、添加用户、角色等功能 |
| 159 | + |
| 160 | + |
| 161 | + |
| 162 | +10、点击左侧的User 菜单然后点击用户列表中的用户为该用户添加我们刚创建的`iotdb_admin`角色 |
| 163 | + |
| 164 | + |
| 165 | + |
| 166 | +11、选择Role Mappings ，在Assign role选择`iotdb_admin`增加角色 |
| 167 | + |
| 168 | + |
| 169 | + |
| 170 | + |
| 171 | + |
| 172 | +提示：如果用户角色有调整需要重新生成token并且重新登陆iotdb才会生效 |
| 173 | + |
| 174 | +以上步骤提供了一种 keycloak 登陆 iotdb 方式，更多方式请参考 keycloak 配置 |
| 175 | + |
| 176 | +若对应的 IoTDB 服务器开启了使用 OpenID Connect (OIDC) 作为权限认证服务，那么就不再需要使用用户名密码进行登录。 |
| 177 | +替而代之的是使用 Token，以及空密码。 |
| 178 | +此时，登录命令如下： |
| 179 | + |
| 180 | +```shell |
| 181 | +Shell > bash sbin/start-cli.sh -h 10.129.187.21 -p 6667 -u {my-access-token} -pw "" |
| 182 | +``` |
| 183 | + |
| 184 | +其中，需要将{my-access-token} （注意，包括{}）替换成你的 token，即 access_token 对应的值。密码为空需要再次确认。 |
| 185 | + |
| 186 | + |
| 187 | + |
| 188 | +如何获取 token 取决于你的 OIDC 设置。 最简单的一种情况是使用`password-grant`。例如，假设你在用 keycloack 作为你的 OIDC 服务， |
| 189 | +并且你在 keycloack 中有一个被定义成 public 的`iotdb`客户的 realm，那么你可以使用如下`curl`命令获得 token。 |
| 190 | +（注意例子中的{}和里面的内容需要替换成具体的服务器地址和 realm 名字）： |
| 191 | +```shell |
| 192 | +curl -X POST "http://{your-keycloack-server}/realms/{your-realm}/protocol/openid-connect/token" \ -H "Content-Type: application/x-www-form-urlencoded" \ |
| 193 | + -d "username={username}" \ |
| 194 | + -d "password={password}" \ |
| 195 | + -d 'grant_type=password' \ |
| 196 | + -d "client_id=iotdb-client" |
| 197 | +``` |
| 198 | + |
| 199 | +示例结果如下： |
| 200 | + |
| 201 | +```json |
| 202 | +{"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"} |
| 203 | +``` |
| 204 | + |
| 205 | +## 5. Cli 的批量操作 |
| 206 | +当您想要通过脚本的方式通过 Cli / Shell 对 IoTDB 进行批量操作时，可以使用-e 参数。通过使用该参数，您可以在不进入客户端输入模式的情况下操作 IoTDB。 |
| 207 | + |
| 208 | +为了避免 SQL 语句和其他参数混淆，现在只支持-e 参数作为最后的参数使用。 |
| 209 | + |
| 210 | +针对 cli/Shell 工具的-e 参数用法如下： |
| 211 | + |
| 212 | +Linux 系统与 MacOS 指令： |
| 213 | + |
| 214 | +```shell |
| 215 | +Shell > bash sbin/start-cli.sh -h {host} -p {rpcPort} -u {user} -pw {password} -e {sql for iotdb} |
| 216 | +``` |
| 217 | + |
| 218 | +Windows 系统指令 |
| 219 | +```shell |
| 220 | +# V2.0.4.x 版本之前 |
| 221 | +Shell > sbin\start-cli.bat -h {host} -p {rpcPort} -u {user} -pw {password} -e {sql for iotdb} |
| 222 | + |
| 223 | +# V2.0.4.x 版本及之后 |
| 224 | +Shell > sbin\windows\start-cli.bat -h {host} -p {rpcPort} -u {user} -pw {password} -e {sql for iotdb} |
| 225 | +``` |
| 226 | + |
| 227 | +在 Windows 环境下，-e 参数的 SQL 语句需要使用` `` `对于`" "`进行替换 |
| 228 | + |
| 229 | +为了更好的解释-e 参数的使用，可以参考下面在 Linux 上执行的例子。 |
| 230 | + |
| 231 | +假设用户希望对一个新启动的 IoTDB 进行如下操作： |
| 232 | + |
| 233 | +1. 创建名为 root.demo 的 database |
| 234 | + |
| 235 | +2. 创建名为 root.demo.s1 的时间序列 |
| 236 | + |
| 237 | +3. 向创建的时间序列中插入三个数据点 |
| 238 | + |
| 239 | +4. 查询验证数据是否插入成功 |
| 240 | + |
| 241 | +那么通过使用 cli/Shell 工具的 -e 参数，可以采用如下的脚本： |
| 242 | + |
| 243 | +```shell |
| 244 | +# !/bin/bash |
| 245 | + |
| 246 | +host=127.0.0.1 |
| 247 | +rpcPort=6667 |
| 248 | +user=root |
| 249 | +pass=root |
| 250 | + |
| 251 | +bash ./sbin/start-cli.sh -h ${host} -p ${rpcPort} -u ${user} -pw ${pass} -e "CREATE DATABASE root.demo" |
| 252 | +bash ./sbin/start-cli.sh -h ${host} -p ${rpcPort} -u ${user} -pw ${pass} -e "create timeseries root.demo.s1 WITH DATATYPE=INT32, ENCODING=RLE" |
| 253 | +bash ./sbin/start-cli.sh -h ${host} -p ${rpcPort} -u ${user} -pw ${pass} -e "insert into root.demo(timestamp,s1) values(1,10)" |
| 254 | +bash ./sbin/start-cli.sh -h ${host} -p ${rpcPort} -u ${user} -pw ${pass} -e "insert into root.demo(timestamp,s1) values(2,11)" |
| 255 | +bash ./sbin/start-cli.sh -h ${host} -p ${rpcPort} -u ${user} -pw ${pass} -e "insert into root.demo(timestamp,s1) values(3,12)" |
| 256 | +bash ./sbin/start-cli.sh -h ${host} -p ${rpcPort} -u ${user} -pw ${pass} -e "select s1 from root.demo" |
| 257 | +``` |
| 258 | + |
| 259 | +打印出来的结果显示如下，通过这种方式进行的操作与客户端的输入模式以及通过 JDBC 进行操作结果是一致的。 |
| 260 | + |
| 261 | +```shell |
| 262 | + Shell > bash ./shell.sh |
| 263 | ++-----------------------------+------------+ |
| 264 | +| Time|root.demo.s1| |
| 265 | ++-----------------------------+------------+ |
| 266 | +|1970-01-01T08:00:00.001+08:00| 10| |
| 267 | +|1970-01-01T08:00:00.002+08:00| 11| |
| 268 | +|1970-01-01T08:00:00.003+08:00| 12| |
| 269 | ++-----------------------------+------------+ |
| 270 | +Total line number = 3 |
| 271 | +It costs 0.267s |
| 272 | +``` |
| 273 | + |
| 274 | +需要特别注意的是，在脚本中使用 -e 参数时要对特殊字符进行转义。 |
| 275 | + |
0 commit comments