| <!-- |
| |
| Licensed to the Apache Software Foundation (ASF) under one |
| or more contributor license agreements. See the NOTICE file |
| distributed with this work for additional information |
| regarding copyright ownership. The ASF licenses this file |
| to you under the Apache License, Version 2.0 (the |
| "License"); you may not use this file except in compliance |
| with the License. You may obtain a copy of the License at |
| |
| http://www.apache.org/licenses/LICENSE-2.0 |
| |
| Unless required by applicable law or agreed to in writing, |
| software distributed under the License is distributed on an |
| "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY |
| KIND, either express or implied. See the License for the |
| specific language governing permissions and limitations |
| under the License. |
| |
| --> |
| |
| # 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 `TimechoDB@2021`(Before V2.0.6 it 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 <br> |
| 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.<br> |
| 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 |
| # Before version V2.0.6.x |
| Shell > bash sbin/start-cli.sh -h 127.0.0.1 -p 6667 -u root -pw root |
| |
| # V2.0.6.x and later versions |
| Shell > bash sbin/start-cli.sh -h 127.0.0.1 -p 6667 -u root -pw TimechoDB@2021 |
| ``` |
| |
| 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, before version V2.0.6.x |
| Shell > sbin\windows\start-cli.bat -h 127.0.0.1 -p 6667 -u root -pw root |
| |
| # V2.0.6.x and later versions |
| Shell > sbin\windows\start-cli.bat -h 127.0.0.1 -p 6667 -u root -pw TimechoDB@2021 |
| ``` |
| |
| After operating these commands, the cli can be started successfully. The successful status will be as follows: |
| |
| ``` |
| _____ _________ ______ ______ |
| |_ _| | _ _ ||_ _ `.|_ _ \ |
| | | .--.|_/ | | \_| | | `. \ | |_) | |
| | | / .'`\ \ | | | | | | | __'. |
| _| |_| \__. | _| |_ _| |_.' /_| |__) | |
| |_____|'.__.' |_____| |______.'|_______/ version <version> |
| |
| |
| Successfully login at 127.0.0.1:6667 |
| IoTDB> |
| ``` |
| |
| Enter ```quit``` or `exit` can exit Cli. |
| |
| ## 2. Cli Parameters |
| |
| | **Parameter** | **Type** | **Required** | **Description** | **Example** | |
| | -------------------------- | -------- | ------------ |-----------------------------------------------------------------------------------| ------------------- | |
| | -h `<host>` | string | No | The IP address of the IoTDB server. (Default: 127.0.0.1) | -h 127.0.0.1 | |
| | -p `<rpcPort>` | int | No | The RPC port of the IoTDB server. (Default: 6667) | -p 6667 | |
| | -u `<username>` | string | No | The username to connect to the IoTDB server. (Default: root) | -u root | |
| | -pw `<password>` | string | No | The password to connect to the IoTDB server. (Default: root) | -pw root | |
| | -sql_dialect `<sql_dialect>` | string | No | The data model type: tree or table. (Default: tree) | -sql_dialect table | |
| | -e `<execute>` | string | No | Batch operations in non-interactive mode. | -e "show databases" | |
| | -c | Flag | No | Required if rpc_thrift_compression_enable=true on the server. | -c | |
| | -disableISO8601 | Flag | No | If set, timestamps will be displayed as numeric values instead of ISO8601 format. | -disableISO8601 | |
| | -usessl `<use_ssl>` | Boolean | No | Enable SSL connection | -usessl true | |
| | -ts `<trust_store>` | string | No | SSL certificate store path | -ts /path/to/truststore | |
| | -tpw `<trust_store_pwd>` | string | No | SSL certificate store password | -tpw myTrustPassword | |
| | -timeout `<queryTimeout>` | int | No | Query timeout (seconds). If not set, the server's configuration will be used. | -timeout 30 | |
| | -help | Flag | No | Displays help information for the CLI tool. | -help | |
| |
| 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. 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. |
| |
| ## 5. Access History Feature |
| |
| Since IoTDB **V2.0.9.1**, the access history feature is supported. After a client logs in successfully, key historical access information is displayed, and the feature supports distributed scenarios. Both administrators and regular users can only view their own access history. The core displayed information includes: |
| |
| - Last successful session: displays date, time, access application, IP address, and access method (not shown for first login or when no history exists). |
| - Most recent failed attempt: displays the date, time, access application, IP address, and access method of the latest failed login attempt before the current successful login. |
| - Cumulative failed attempts: total number of failed session attempts since the last successful session was established. |
| |
| ### 5.1 Enabling Access History |
| |
| You can enable or disable the access history feature by modifying relevant parameters in the `iotdb-system.properties` file. A restart is required for changes to take effect. For example: |
| |
| ```Plain |
| # Controls whether the audit log feature is enabled |
| enable_audit_log=false |
| ``` |
| |
| - When enabled: login information is recorded and expired data is cleaned periodically. |
| - When disabled: no data is recorded, displayed, or cleaned. |
| - If disabled and then re-enabled, the displayed history will be the last record before disabling, which may not represent the actual latest login. |
| |
| Usage example: |
| |
| ```Bash |
| --------------------- |
| Starting IoTDB Cli |
| --------------------- |
| _____ _________ ______ ______ |
| |_ _| | _ _ ||_ _ `.|_ _ \ |
| | | .--.|_/ | | \_| | | `. \ | |_) | |
| | | / .'`\ \ | | | | | | | __'. |
| _| |_| \__. | _| |_ _| |_.' /_| |__) | |
| |_____|'.__.' |_____| |______.'|_______/ Enterprise version 2.0.9.1 (Build: xxxxxxx) |
| |
| |
| ---Last Successful Session------------------ |
| Time: 2026-03-24T10:25:47.759+08:00 |
| IP Address: 127.0.0.1 |
| ---Last Failed Session---------------------- |
| Time: 2026-03-24T10:27:26.314+08:00 |
| IP Address: 127.0.0.1 |
| Cumulative Failed Attempts: 1 |
| Successfully login at 127.0.0.1:6667 |
| IoTDB> |
| ``` |
| |
| ### 5.2 Viewing Access History |
| |
| The `root` user and users with the `AUDIT` privilege can view access history records using SQL statements. |
| |
| Syntax: |
| |
| ```SQL |
| SELECT * FROM root.__audit.login.u_{userid}.** |
| ``` |
| |
| The `userid` can be obtained using the `LIST USER` statement. |
| |
| Example: |
| |
| ```SQL |
| IoTDB> SELECT * FROM root.__audit.login.** |
| +-----------------------------+------------------------------------+--------------------------------+--------------------------------------+ |
| | Time|root.__audit.login.u_0.node_1.result|root.__audit.login.u_0.node_1.ip|root.__audit.login.u_0.node_1.username| |
| +-----------------------------+------------------------------------+--------------------------------+--------------------------------------+ |
| |2026-03-25T10:55:58.240+08:00| true| 127.0.0.1| root| |
| +-----------------------------+------------------------------------+--------------------------------+--------------------------------------+ |
| Total line number = 1 |
| It costs 0.039s |
| |
| IoTDB> SELECT * FROM root.__audit.login.u_0.** |
| +-----------------------------+------------------------------------+--------------------------------+--------------------------------------+ |
| | Time|root.__audit.login.u_0.node_1.result|root.__audit.login.u_0.node_1.ip|root.__audit.login.u_0.node_1.username| |
| +-----------------------------+------------------------------------+--------------------------------+--------------------------------------+ |
| |2026-03-25T10:55:58.240+08:00| true| 127.0.0.1| root| |
| +-----------------------------+------------------------------------+--------------------------------+--------------------------------------+ |
| Total line number = 1 |
| It costs 0.020s |
| ``` |
