From 7c3d6a35b4516fa3186b9b70b98835ef200676a8 Mon Sep 17 00:00:00 2001 From: Linhe Huo Date: Wed, 19 Mar 2025 10:10:06 +0800 Subject: [PATCH] docs: add password tutorial for all components (#30253) Close [TS-6000](https://jira.taosdata.com:18080/browse/TS-6000) --- docs/en/27-train-faq/03-password.md | 296 ++++++++++++++++++++++++++++ docs/zh/27-train-faq/03-password.md | 296 ++++++++++++++++++++++++++++ 2 files changed, 592 insertions(+) create mode 100644 docs/en/27-train-faq/03-password.md create mode 100644 docs/zh/27-train-faq/03-password.md diff --git a/docs/en/27-train-faq/03-password.md b/docs/en/27-train-faq/03-password.md new file mode 100644 index 0000000000..f6029b5092 --- /dev/null +++ b/docs/en/27-train-faq/03-password.md @@ -0,0 +1,296 @@ +--- +title: Usage of Special Characters in Passwords +description: Usage of special characters in user passwords in TDengine +--- + +import Tabs from "@theme/Tabs"; +import TabItem from "@theme/TabItem"; + +TDengine user passwords must meet the following rules: + +1. The username must not exceed 23 bytes. +2. The password length must be between 8 and 255 characters. +3. The range of password characters: + 1. Uppercase letters: `A-Z` + 2. Lowercase letters: `a-z` + 3. Numbers: `0-9` + 4. Special characters: `! @ # $ % ^ & * ( ) - _ + = [ ] { } : ; > < ? | ~ , .` +4. When strong password is enabled (EnableStrongPassword 1, enabled by default), the password must contain at least three of the following categories: uppercase letters, lowercase letters, numbers, and special characters. When not enabled, there are no restrictions on character types. + +## Usage Guide for Special Characters in Different Components + +Take the username `user1` and password `Ab1!@#$%^&*()-_+=[]{}` as an example. + +```sql +CREATE USER user1 PASS 'Ab1!@#$%^&*()-_+=[]{}'; +``` + + + + +In the [TDengine Command Line Interface (CLI)](../../tdengine-reference/tools/tdengine-cli/), note the following: + +- If the `-p` parameter is used without a password, you will be prompted to enter a password, and any acceptable characters can be entered. +- If the `-p` parameter is used with a password, and the password contains special characters, single quotes must be used. + +Login with user `user1`: + +```shell +taos -u user1 -p'Ab1!@#$%^&*()-_+=[]{}' +taos -u user1 -pAb1\!\@\#\$\%\^\&\*\(\)\-\_\+\=\[\]\{\} +``` + + + + +In [taosdump](../../tdengine-reference/tools/taosdump/), note the following: + +- If the `-p` parameter is used without a password, you will be prompted to enter a password, and any acceptable characters can be entered. +- If the `-p` parameter is used with a password, and the password contains special characters, single quotes or escaping must be used. + +Backup database `test` with user `user1`: + +```shell +taosdump -u user1 -p'Ab1!@#$%^&*()-_+=[]{}' -D test +taosdump -u user1 -pAb1\!\@\#\$\%\^\&\*\(\)\-\_\+\=\[\]\{\} -D test +``` + + + + +In [taosBenchmark](../../tdengine-reference/tools/taosbenchmark/), note the following: + +- If the `-p` parameter is used without a password, you will be prompted to enter a password, and any acceptable characters can be entered. +- If the `-p` parameter is used with a password, and the password contains special characters, single quotes or escaping must be used. + +Example of data write test with user `user1`: + +```shell +taosBenchmark -u user1 -p'Ab1!@#$%^&*()-_+=[]{}' -d test -y +``` + +When using `taosBenchmark -f `, there are no restrictions on the password in the JSON file. + + + + +[taosX](../../tdengine-reference/components/taosx/) uses DSN to represent TDengine connections, in the format: `(taos|tmq)[+ws]://:@:`, where `` can contain special characters, such as: `taos+ws://user1:Ab1!@#$%^&*()-_+=[]{}@192.168.10.10:6041`. + +Example of exporting data with user `user1`: + +```shell +taosx -f 'taos://user1:Ab1!@#$%^&*()-_+=[]{}@localhost:6030?query=select * from test.t1' -t 'csv:./test.csv' +``` + +Note that if the password can be URL decoded, the URL decoded result will be used as the password. For example: `taos+ws://user1:Ab1%21%40%23%24%25%5E%26%2A%28%29-_%2B%3D%5B%5D%7B%7D@localhost:6041` is equivalent to `taos+ws://user1:Ab1!@#$%^&*()-_+=[]{}@localhost:6041`. + + + + + +No special handling is required in [Explorer](../../tdengine-reference/components/taosexplorer/), just use it directly. + + + + + +When using special character passwords in JDBC, the password needs to be URL encoded, as shown below: + +```java +package com.taosdata.example; + +import java.sql.Connection; +import java.sql.DriverManager; +import java.sql.SQLException; +import java.util.Properties; +import java.net.URLEncoder; +import java.nio.charset.StandardCharsets; + +import com.taosdata.jdbc.TSDBDriver; + +public class JdbcPassDemo { + public static void main(String[] args) throws Exception { + String password = "Ab1!@#$%^&*()-_+=[]{}"; + String encodedPassword = URLEncoder.encode(password, StandardCharsets.UTF_8.toString()); + String jdbcUrl = "jdbc:TAOS-WS://localhost:6041"; + Properties connProps = new Properties(); + connProps.setProperty(TSDBDriver.PROPERTY_KEY_USER, "user1"); + connProps.setProperty(TSDBDriver.PROPERTY_KEY_PASSWORD, encodedPassword); + connProps.setProperty(TSDBDriver.PROPERTY_KEY_ENABLE_AUTO_RECONNECT, "true"); + connProps.setProperty(TSDBDriver.PROPERTY_KEY_CHARSET, "UTF-8"); + connProps.setProperty(TSDBDriver.PROPERTY_KEY_TIME_ZONE, "UTC-8"); + + try (Connection conn = DriverManager.getConnection(jdbcUrl, connProps)) { + System.out.println("Connected to " + jdbcUrl + " successfully."); + + // you can use the connection for execute SQL here + + } catch (Exception ex) { + // please refer to the JDBC specifications for detailed exceptions info + System.out.printf("Failed to connect to %s, %sErrMessage: %s%n", + jdbcUrl, + ex instanceof SQLException ? "ErrCode: " + ((SQLException) ex).getErrorCode() + ", " : "", + ex.getMessage()); + // Print stack trace for context in examples. Use logging in production. + ex.printStackTrace(); + throw ex; + } + } +} +``` + + + + +No special handling is required for special character passwords in Python, as shown below: + +```python +import taos +import taosws + + +def create_connection(): + host = "localhost" + port = 6030 + return taos.connect( + user="user1", + password="Ab1!@#$%^&*()-_+=[]{}", + host=host, + port=port, + ) + +def create_ws_connection(): + host = "localhost" + port = 6041 + return taosws.connect( + user="user1", + password="Ab1!@#$%^&*()-_+=[]{}", + host=host, + port=port, + ) + + +def show_databases(conn): + cursor = conn.cursor() + cursor.execute("show databases") + print(cursor.fetchall()) + cursor.close() + + +if __name__ == "__main__": + print("Connect with native protocol") + conn = create_connection() + show_databases(conn) + print("Connect with websocket protocol") + conn = create_ws_connection() + show_databases(conn) + +``` + + + + + +Starting from version 3.6.0, Go supports passwords containing special characters, which need to be encoded using encodeURIComponent. + +```go +package main + +import ( + "database/sql" + "fmt" + "log" + "net/url" + + _ "github.com/taosdata/driver-go/v3/taosWS" +) + +func main() { + var user = "user1" + var password = "Ab1!@#$%^&*()-_+=[]{}" + var encodedPassword = url.QueryEscape(password) + var taosDSN = user + ":" + encodedPassword + "@ws(localhost:6041)/" + taos, err := sql.Open("taosWS", taosDSN) + if err != nil { + log.Fatalln("Failed to connect to " + taosDSN + "; ErrMessage: " + err.Error()) + } + fmt.Println("Connected to " + taosDSN + " successfully.") + defer taos.Close() +} +``` + + + + +In Rust, DSN is used to represent TDengine connections, in the format: `(taos|tmq)[+ws]://:@:`, where `` can contain special characters, such as: `taos+ws://user1:Ab1!@#$%^&*()-_+=[]{}@192.168.10.10:6041`. + +```rust +let dsn = "taos+ws://user1:Ab1!@#$%^&*()-_+=[]{}@localhost:6041"; +let connection = TaosBuilder::from_dsn(&dsn)?.build().await?; +``` + + + + +```js +const taos = require("@tdengine/websocket"); + +let dsn = 'ws://localhost:6041'; +async function createConnect() { + try { + let conf = new taos.WSConfig(dsn); + conf.setUser('user1'); + conf.setPwd('Ab1!@#$%^&*()-_+=[]{}'); + conf.setDb('test'); + conn = await taos.sqlConnect(conf); + console.log("Connected to " + dsn + " successfully."); + return conn; + } catch (err) { + console.log("Failed to connect to " + dsn + ", ErrCode: " + err.code + ", ErrMessage: " + err.message); + throw err; + } +} + +createConnect() +``` + + + + +When using passwords in C#, note that connection strings do not support semicolons (as semicolons are delimiters). In this case, you can construct the `ConnectionStringBuilder` without a password, and then set the username and password. + +As shown below: + +```csharp +var builder = new ConnectionStringBuilder("host=localhost;port=6030"); +builder.Username = "user1"; +builder.Password = "Ab1!@#$%^&*()-_+=[]{}"; +using (var client = DbDriver.Open(builder)){} +``` + + + + +There are no restrictions on passwords in C. + +```c +TAOS *taos = taos_connect("localhost", "user1", "Ab1!@#$%^&*()-_+=[]{}", NULL, 6030); +``` + + + + +When using passwords in REST API, note the following: + +- Passwords use Basic Auth, in the format `Authorization: Basic base64(:)`. +- Passwords containing colons `:` are not supported. + +The following two methods are equivalent: + +```shell +curl -u'user1:Ab1!@#$%^&*()-_+=[]{}' -d 'show databases' http://localhost:6041/rest/sql +curl -H 'Authorization: Basic dXNlcjE6QWIxIUAjJCVeJiooKS1fKz1bXXt9' -d 'show databases' http://localhost:6041/rest/sql +``` + + + diff --git a/docs/zh/27-train-faq/03-password.md b/docs/zh/27-train-faq/03-password.md new file mode 100644 index 0000000000..7ea215999d --- /dev/null +++ b/docs/zh/27-train-faq/03-password.md @@ -0,0 +1,296 @@ +--- +title: 密码中特殊字符的使用 +description: TDengine 用户密码中特殊字符的使用 +--- + +import Tabs from "@theme/Tabs"; +import TabItem from "@theme/TabItem"; + +TDengine 用户密码需满足以下规则： + +1. 用户名最长不超过 23 个字节。 +2. 密码长度必须为 8 到 255 位。 +3. 密码字符的取值范围 + 1. 大写字母：`A-Z` + 2. 小写字母：`a-z` + 3. 数字：`0-9` + 4. 特殊字符： `! @ # $ % ^ & * ( ) - _ + = [ ] { } : ; > < ? | ~ , .` +4. 强密码启用（EnableStrongPassword 1，默认开启）时，至少包含大写字母、小写字母、数字、特殊字符中的三类，不启用时，字符种类不做约束。 + +## 各组件特殊字符使用指南 + +以用户名 `user1`，密码 `Ab1!@#$%^&*()-_+=[]{}` 为例。 + +```sql +CREATE USER user1 PASS 'Ab1!@#$%^&*()-_+=[]{}'; +``` + + + + +在 [TDengine 命令行客户端（CLI）](../../reference/tools/taos-cli/) 中使用需要注意以下几点： + +- 使用参数 `-p` 后不带密码，会提示输入密码，可输入任意可接收字符。 +- 使用参数 `-p` 后带密码，如果密码中包含特殊字符，需使用单引号。 + +使用用户 `user1` 登录： + +```shell +taos -u user1 -p'Ab1!@#$%^&*()-_+=[]{}' +taos -u user1 -pAb1\!\@\#\$\%\^\&\*\(\)\-\_\+\=\[\]\{\} +``` + + + + +在 [taosdump](../../reference/tools/taosdump/) 中使用需要注意以下几点： + +- 使用参数 `-p` 后不带密码，会提示输入密码，可输入任意可接收字符。 +- 使用参数 `-p` 后带密码，如果密码中包含特殊字符，需使用单引号或进行转义。 + +使用用户 `user1` 备份数据库 `test`： + +```shell +taosdump -u user1 -p'Ab1!@#$%^&*()-_+=[]{}' -D test +taosdump -u user1 -pAb1\!\@\#\$\%\^\&\*\(\)\-\_\+\=\[\]\{\} -D test +``` + + + + +在 [taosBenchmark](../../reference/tools/taosbenchmark/) 中使用需要注意以下几点： + +- 使用参数 `-p` 后不带密码，会提示输入密码，可输入任意可接收字符。 +- 使用参数 `-p` 后带密码，如果密码中包含特殊字符，需使用单引号或进行转义。 + +使用用户 `user1` 进行数据写入测试示例如下： + +```shell +taosBenchmark -u user1 -p'Ab1!@#$%^&*()-_+=[]{}' -d test -y +``` + +使用 `taosBenchmark -f ` 方式时，JSON 文件中密码使用无限制。 + + + + +[taosX](../../reference/components/taosx/) 使用 DSN 表示 TDengine 连接，使用如下格式：`(taos|tmq)[+ws]://:@:`，其中 `` 可以包含特殊字符，如：`taos+ws://user1:Ab1!@#$%^&*()-_+=[]{}@192.168.10.10:6041`。 + +使用用户 `user1` 导出数据示例如下： + +```shell +taosx -f 'taos://user1:Ab1!@#$%^&*()-_+=[]{}@localhost:6030?query=select * from test.t1' -t 'csv:./test.csv' +``` + +需要注意的是，如果密码可被 URL decode，则会使用 URL decoded 结果作为密码。如：`taos+ws://user1:Ab1%21%40%23%24%25%5E%26%2A%28%29-_%2B%3D%5B%5D%7B%7D@localhost:6041` 与 `taos+ws://user1:Ab1!@#$%^&*()-_+=[]{}@localhost:6041` 是等价的。 + + + + + +在 [Explorer](../../reference/components/explorer/) 中无需特殊处理，直接使用即可。 + + + + + +在 JDBC 中使用特殊字符密码时，密码需要通过 URL 编码，示例如下： + +```java +package com.taosdata.example; + +import java.sql.Connection; +import java.sql.DriverManager; +import java.sql.SQLException; +import java.util.Properties; +import java.net.URLEncoder; +import java.nio.charset.StandardCharsets; + +import com.taosdata.jdbc.TSDBDriver; + +public class JdbcPassDemo { + public static void main(String[] args) throws Exception { + String password = "Ab1!@#$%^&*()-_+=[]{}"; + String encodedPassword = URLEncoder.encode(password, StandardCharsets.UTF_8.toString()); + String jdbcUrl = "jdbc:TAOS-WS://localhost:6041"; + Properties connProps = new Properties(); + connProps.setProperty(TSDBDriver.PROPERTY_KEY_USER, "user1"); + connProps.setProperty(TSDBDriver.PROPERTY_KEY_PASSWORD, encodedPassword); + connProps.setProperty(TSDBDriver.PROPERTY_KEY_ENABLE_AUTO_RECONNECT, "true"); + connProps.setProperty(TSDBDriver.PROPERTY_KEY_CHARSET, "UTF-8"); + connProps.setProperty(TSDBDriver.PROPERTY_KEY_TIME_ZONE, "UTC-8"); + + try (Connection conn = DriverManager.getConnection(jdbcUrl, connProps)) { + System.out.println("Connected to " + jdbcUrl + " successfully."); + + // you can use the connection for execute SQL here + + } catch (Exception ex) { + // please refer to the JDBC specifications for detailed exceptions info + System.out.printf("Failed to connect to %s, %sErrMessage: %s%n", + jdbcUrl, + ex instanceof SQLException ? "ErrCode: " + ((SQLException) ex).getErrorCode() + ", " : "", + ex.getMessage()); + // Print stack trace for context in examples. Use logging in production. + ex.printStackTrace(); + throw ex; + } + } +} +``` + + + + +在 Python 中使用特殊字符密码无需特殊处理，示例如下： + +```python +import taos +import taosws + + +def create_connection(): + host = "localhost" + port = 6030 + return taos.connect( + user="user1", + password="Ab1!@#$%^&*()-_+=[]{}", + host=host, + port=port, + ) + +def create_ws_connection(): + host = "localhost" + port = 6041 + return taosws.connect( + user="user1", + password="Ab1!@#$%^&*()-_+=[]{}", + host=host, + port=port, + ) + + +def show_databases(conn): + cursor = conn.cursor() + cursor.execute("show databases") + print(cursor.fetchall()) + cursor.close() + + +if __name__ == "__main__": + print("Connect with native protocol") + conn = create_connection() + show_databases(conn) + print("Connect with websocket protocol") + conn = create_ws_connection() + show_databases(conn) + +``` + + + + + +从 3.6.0 版本开始，Go 语言中支持密码中包含特殊字符，使用时需要 encodeURIComponent 编码。 + +```go +package main + +import ( + "database/sql" + "fmt" + "log" + "net/url" + + _ "github.com/taosdata/driver-go/v3/taosWS" +) + +func main() { + var user = "user1" + var password = "Ab1!@#$%^&*()-_+=[]{}" + var encodedPassword = url.QueryEscape(password) + var taosDSN = user + ":" + encodedPassword + "@ws(localhost:6041)/" + taos, err := sql.Open("taosWS", taosDSN) + if err != nil { + log.Fatalln("Failed to connect to " + taosDSN + "; ErrMessage: " + err.Error()) + } + fmt.Println("Connected to " + taosDSN + " successfully.") + defer taos.Close() +} +``` + + + + +Rust 中使用 DSN 表示 TDengine 连接，使用如下格式：`(taos|tmq)[+ws]://:@:`，其中 `` 可以包含特殊字符，如：`taos+ws://user1:Ab1!@#$%^&*()-_+=[]{}@192.168.10.10:6041`。 + +```rust +let dsn = "taos+ws://user1:Ab1!@#$%^&*()-_+=[]{}@localhost:6041"; +let connection = TaosBuilder::from_dsn(&dsn)?.build().await?; +``` + + + + +```js +const taos = require("@tdengine/websocket"); + +let dsn = 'ws://localhost:6041'; +async function createConnect() { + try { + let conf = new taos.WSConfig(dsn); + conf.setUser('user1'); + conf.setPwd('Ab1!@#$%^&*()-_+=[]{}'); + conf.setDb('test'); + conn = await taos.sqlConnect(conf); + console.log("Connected to " + dsn + " successfully."); + return conn; + } catch (err) { + console.log("Failed to connect to " + dsn + ", ErrCode: " + err.code + ", ErrMessage: " + err.message); + throw err; + } +} + +createConnect() +``` + + + + +在 C# 中使用密码时，需要注意：使用连接字符串时，不支持分号（因分号为分隔符）；此时可使用不带密码的字符串构建 `ConnectionStringBuilder`，之后再设置用户名和密码。 + +示例如下： + +```csharp +var builder = new ConnectionStringBuilder("host=localhost;port=6030"); +builder.Username = "user1"; +builder.Password = "Ab1!@#$%^&*()-_+=[]{}"; +using (var client = DbDriver.Open(builder)){} +``` + + + + +C 语言中使用密码无限制。 + +```c +TAOS *taos = taos_connect("localhost", "user1", "Ab1!@#$%^&*()-_+=[]{}", NULL, 6030); +``` + + + + +REST API 中使用密码时，需要注意以下几点： + +- 密码使用 Basic Auth，格式为 `Authorization: Basic base64(:)`。 +- 不支持密码中包含冒号 `:`。 + +以下两种方式等价： + +```shell +curl -u'user1:Ab1!@#$%^&*()-_+=[]{}' -d 'show databases' http://localhost:6041/rest/sql +curl -H 'Authorization: Basic dXNlcjE6QWIxIUAjJCVeJiooKS1fKz1bXXt9' -d 'show databases' http://localhost:6041/rest/sql +``` + + +