This is an automated email from the ASF dual-hosted git repository.
qiaojialin pushed a commit to branch main
in repository https://gitbox.apache.org/repos/asf/iotdb-docs.git
The following commit(s) were added to refs/heads/main by this push:
new 9db5ffc auth.add eng doc. (#113)
9db5ffc is described below
commit 9db5ffc09576369a1cc8e8e4e9111093c9625f1a
Author: Colin Li <105656576+shuol...@users.noreply.github.com>
AuthorDate: Thu Dec 7 11:46:45 2023 +0800
auth.add eng doc. (#113)
---
.../Master/User-Manual/Authority-Management.md | 704 ++++++++++-----------
.../Master/User-Manual/Authority-Management.md | 150 +++--
2 files changed, 459 insertions(+), 395 deletions(-)
diff --git a/src/UserGuide/Master/User-Manual/Authority-Management.md
b/src/UserGuide/Master/User-Manual/Authority-Management.md
index 15c0447..1c46894 100644
--- a/src/UserGuide/Master/User-Manual/Authority-Management.md
+++ b/src/UserGuide/Master/User-Manual/Authority-Management.md
@@ -21,509 +21,499 @@
# Administration Management
-IoTDB provides users with account privilege management operations, so as to
ensure data security.
+IoTDB provides permission management operations, offering users the ability to
manage permissions for data and cluster systems, ensuring data and system
security.
-We will show you basic user privilege management operations through the
following specific examples. Detailed SQL syntax and usage details can be found
in [SQL Documentation](../Reference/SQL-Reference.md).
-At the same time, in the JAVA programming environment, you can use the [Java
JDBC](../API/Programming-JDBC.md) to execute privilege management statements in
a single or batch mode.
+This article introduces the basic concepts of the permission module in IoTDB,
including user definition, permission management, authentication logic, and use
cases. In the JAVA programming environment, you can use the [JDBC
API](https://chat.openai.com/API/Programming-JDBC.md) to execute permission
management statements individually or in batches.
## Basic Concepts
### User
-The user is the legal user of the database. A user corresponds to a unique
username and has a password as a means of authentication. Before using a
database, a person must first provide a legitimate username and password to
make himself/herself a user.
+A user is a legitimate user of the database. Each user corresponds to a unique
username and has a password as a means of authentication. Before using the
database, a person must provide a valid (i.e., stored in the database) username
and password for a successful login.
-### Privilege
+### Permission
-The database provides a variety of operations, and not all users can perform
all operations. If a user can perform an operation, the user is said to have
the privilege to perform the operation. privileges are divided into data
management privilege (such as adding, deleting and modifying data) and
authority management privilege (such as creation and deletion of users and
roles, granting and revoking of privileges, etc.). Data management privilege
often needs a path to limit its effective [...]
+The database provides various operations, but not all users can perform all
operations. If a user can perform a certain operation, they are said to have
permission to execute that operation. Permissions are typically limited in
scope by a path, and [path
patterns](https://chat.openai.com/Basic-Concept/Data-Model-and-Terminology.md)
can be used to manage permissions flexibly.
### Role
-A role is a set of privileges and has a unique role name as an identifier. A
user usually corresponds to a real identity (such as a traffic dispatcher),
while a real identity may correspond to multiple users. These users with the
same real identity tend to have the same privileges. Roles are abstractions
that can unify the management of such privileges.
+A role is a collection of multiple permissions and has a unique role name as
an identifier. Roles often correspond to real-world identities (e.g., a traffic
dispatcher), and a real-world identity may correspond to multiple users. Users
with the same real-world identity often have the same permissions, and roles
are abstractions for unified management of such permissions.
-### Default User
+### Default Users and Roles
-There is a default user in IoTDB after the initial installation: root, and the
default password is root. This user is an administrator user, who cannot be
deleted and has all the privileges. Neither can new privileges be granted to
the root user nor can privileges owned by the root user be deleted.
+After installation and initialization, IoTDB includes a default user: root,
with the default password root. This user is an administrator with fixed
permissions, which cannot be granted or revoked and cannot be deleted. There is
only one administrator user in the database.
-## Privilege Management Operation Examples
+A newly created user or role does not have any permissions initially.
-According to the [sample
data](https://github.com/thulab/iotdb/files/4438687/OtherMaterial-Sample.Data.txt),
the sample data of IoTDB might belong to different power generation groups
such as ln, sgcc, etc. Different power generation groups do not want others to
obtain their own database data, so we need to have data privilege isolated at
the group layer.
+## User Definition
-### Create User
+Users with MANAGE_USER and MANAGE_ROLE permissions or administrators can
create users or roles. Creating a user must meet the following constraints.
-We use `CREATE USER <userName> <password>` to create users. For example, we
can use root user who has all privileges to create two users for ln and sgcc
groups, named ln\_write\_user and sgcc\_write\_user, with both passwords being
write\_pwd. It is recommended to wrap the username in backtick(`). The SQL
statement is:
+### Username Constraints
-```
-CREATE USER `ln_write_user` 'write_pwd'
-CREATE USER `sgcc_write_user` 'write_pwd'
-```
+4 to 32 characters, supports the use of uppercase and lowercase English
letters, numbers, and special characters (`!@#$%^&*()_+-=`).
-Then use the following SQL statement to show the user:
+Users cannot create users with the same name as the administrator.
-```
-LIST USER
-```
+### Password Constraints
-As can be seen from the result shown below, the two users have been created:
+4 to 32 characters, can use uppercase and lowercase letters, numbers, and
special characters (`!@#$%^&*()_+-=`). Passwords are encrypted by default using
MD5.
-```
-IoTDB> CREATE USER `ln_write_user` 'write_pwd'
-Msg: The statement is executed successfully.
-IoTDB> CREATE USER `sgcc_write_user` 'write_pwd'
-Msg: The statement is executed successfully.
-IoTDB> LIST USER
-+---------------+
-| user|
-+---------------+
-| ln_write_user|
-| root|
-|sgcc_write_user|
-+---------------+
-Total line number = 3
-It costs 0.157s
-```
+### Role Name Constraints
-### Grant User Privilege
+4 to 32 characters, supports the use of uppercase and lowercase English
letters, numbers, and special characters (`!@#$%^&*()_+-=`).
-At this point, although two users have been created, they do not have any
privileges, so they can not operate on the database. For example, we use
ln_write_user to write data in the database, the SQL statement is:
+Users cannot create roles with the same name as the administrator.
-```
-INSERT INTO root.ln.wf01.wt01(timestamp,status) values(1509465600000,true)
-```
-The SQL statement will not be executed and the corresponding error prompt is
given as follows:
-```
-IoTDB> INSERT INTO root.ln.wf01.wt01(timestamp,status)
values(1509465600000,true)
-Msg: 602: No permissions for this operation, please add privilege
INSERT_TIMESERIES.
-```
+## Permission Management
-Now, we use root user to grant the two users write privileges to the
corresponding databases.
+IoTDB primarily has two types of permissions: series permissions and global
permissions.
-We use `GRANT USER <userName> PRIVILEGES <privileges> ON <nodeName>` to grant
user privileges(ps: grant create user does not need path). For example:
+### Series Permissions
-```
-GRANT USER `ln_write_user` PRIVILEGES INSERT_TIMESERIES on root.ln.**
-GRANT USER `sgcc_write_user` PRIVILEGES INSERT_TIMESERIES on root.sgcc1.**,
root.sgcc2.**
-GRANT USER `ln_write_user` PRIVILEGES CREATE_USER
-```
+Series permissions constrain the scope and manner in which users access data.
IOTDB support authorization for both absolute paths and prefix-matching paths,
and can be effective at the timeseries granularity.
-The execution result is as follows:
+The table below describes the types and scope of these permissions:
-```
-IoTDB> GRANT USER `ln_write_user` PRIVILEGES INSERT_TIMESERIES on root.ln.**
-Msg: The statement is executed successfully.
-IoTDB> GRANT USER `sgcc_write_user` PRIVILEGES INSERT_TIMESERIES on
root.sgcc1.**, root.sgcc2.**
-Msg: The statement is executed successfully.
-IoTDB> GRANT USER `ln_write_user` PRIVILEGES CREATE_USER
-Msg: The statement is executed successfully.
-```
-Next, use ln_write_user to try to write data again.
-```
-IoTDB> INSERT INTO root.ln.wf01.wt01(timestamp, status) values(1509465600000,
true)
-Msg: The statement is executed successfully.
-```
+| Permission Name | Description
[...]
+|-----------------|-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------
[...]
+| READ_DATA | Allows reading time series data under the authorized path.
[...]
+| WRITE_DATA | Allows reading time series data under the authorized
path.<br/>Allows inserting and deleting time series data under the authorized
path.<br/>Allows importing and loading data under the authorized path. When
importing data, you need the WRITE_DATA permission for the corresponding path.
When automatically creating databases or time series, you need MANAGE_DATABASE
and WRITE_SCHEMA permissions.
[...]
+| READ_SCHEMA | Allows obtaining detailed information about the metadata
tree under the authorized path, <br/>including databases, child paths, child
nodes, devices, time series, templates, views, etc.
[...]
+| WRITE_SCHEMA | Allows obtaining detailed information about the metadata
tree under the authorized path.<br/>Allows creating, deleting, and modifying
time series, templates, views, etc. under the authorized path. When creating or
modifying views, it checks the WRITE_SCHEMA permission for the view path and
READ_SCHEMA permission for the data source. When querying and inserting data
into views, it checks the READ_DATA and WRITE_DATA permissions for the view
path.</br> Allows setting, u [...]
-### Revoker User Privilege
-After granting user privileges, we could use `REVOKE USER <userName>
PRIVILEGES <privileges> ON <nodeName>` to revoke the granted user
privileges(ps: revoke create user does not need path). For example, use root
user to revoke the privilege of ln_write_user and sgcc_write_user:
+### Global Permissions
-```
-REVOKE USER `ln_write_user` PRIVILEGES INSERT_TIMESERIES on root.ln.**
-REVOKE USER `sgcc_write_user` PRIVILEGES INSERT_TIMESERIES on root.sgcc1.**,
root.sgcc2.**
-REVOKE USER `ln_write_user` PRIVILEGES CREATE_USER
-```
+Global permissions constrain the database functions that users can use and
restrict commands that change the system and task state. Once a user obtains
global authorization, they can manage the database.
+The table below describes the types of system permissions:
-The execution result is as follows:
-```
-REVOKE USER `ln_write_user` PRIVILEGES INSERT_TIMESERIES on root.ln.**
-Msg: The statement is executed successfully.
-REVOKE USER `sgcc_write_user` PRIVILEGES INSERT_TIMESERIES on root.sgcc1.**,
root.sgcc2.**
-Msg: The statement is executed successfully.
-REVOKE USER `ln_write_user` PRIVILEGES CREATE_USER
-Msg: The statement is executed successfully.
-```
+| Permission Name | Description
|
+|:---------------:|-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
+| MANAGE_DATABASE | Allow users to create and delete databases.
|
+| MANAGE_USER | Allow users to create, delete, modify, and view users.
|
+| MANAGE_ROLE | Allow users to create, delete, modify, and view roles.
<br/>Allow users to grant/revoke roles to/from other users.
|
+| USE_TRIGGER | Allow users to create, delete, and view
triggers.<br/>Independent of data source permission checks for triggers.
|
+| USE_UDF | Allow users to create, delete, and view user-defined
functions. <br/> Independent of data source permission checks for user-defined
functions. |
+| USE_CQ | Allow users to create, delete, and view continuous
queries. <br/> Independent of data source permission checks for continuous
queries. |
+| USE_PIPE | Allow users to create, start, stop, delete, and view
pipelines. <br/>Allow users to create, delete, and view pipeline plugins.
<br/>Independent of data source permission checks for pipelines. |
+| EXTEND_TEMPLATE | Permission to automatically create templates.
|
+| MAINTAIN | Allow users to query and cancel queries. <br/>Allow users
to view variables. <br/>Allow users to view cluster status.
|
+| USE_MODEL | Allow users to create, delete and view deep learning
model.
|
+Regarding template permissions:
-After revoking, ln_write_user has no permission to writing data to root.ln.**
+1. Only administrators are allowed to create, delete, modify, query, mount,
and unmount templates.
+2. To activate a template, you need to have WRITE_SCHEMA permission for the
activation path.
+3. If automatic creation is enabled, writing to a non-existent path that has a
template mounted will automatically extend the template and insert data.
Therefore, one needs EXTEND_TEMPLATE permission and WRITE_DATA permission for
writing to the sequence.
+4. To deactivate a template, WRITE_SCHEMA permission for the mounted template
path is required.
+5. To query paths that use a specific metadata template, you needs READ_SCHEMA
permission for the paths; otherwise, it will return empty results.
-```
-INSERT INTO root.ln.wf01.wt01(timestamp, status) values(1509465600000, true)
-Msg: 602: No permissions for this operation, please add privilege
INSERT_TIMESERIES.
-```
-### SQL Statements
-Here are all related SQL statements:
+### Granting and Revoking Permissions
-* Create User
+In IoTDB, users can obtain permissions through three methods:
-```
-CREATE USER <userName> <password>;
-Eg: IoTDB > CREATE USER `thulab` 'pwd';
-```
+1. Granted by administrator, who has control over the permissions of other
users.
+2. Granted by a user allowed to authorize permissions, and this user was
assigned the grant option keyword when obtaining the permission.
+3. Granted a certain role by administrator or a user with MANAGE_ROLE, thereby
obtaining permissions.
-* Delete User
+Revoking a user's permissions can be done through the following methods:
-```
-DROP USER <userName>;
-Eg: IoTDB > DROP USER `xiaoming`;
-```
+1. Revoked by administrator.
+2. Revoked by a user allowed to authorize permissions, and this user was
assigned the grant option keyword when obtaining the permission.
+3. Revoked from a user's role by administrator or a user with MANAGE_ROLE,
thereby revoking the permissions.
-* Create Role
+- When granting permissions, a path must be specified. Global permissions need
to be specified as root.**, while series-specific permissions must be absolute
paths or prefix paths ending with a double wildcard.
+- When granting user/role permissions, you can specify the "with grant option"
keyword for that permission, which means that the user can grant permissions on
their authorized paths and can also revoke permissions on other users'
authorized paths. For example, if User A is granted read permission for
`group1.company1.**` with the grant option keyword, then A can grant read
permissions to others on any node or series below `group1.company1`, and can
also revoke read permissions on any nod [...]
+- When revoking permissions, the revocation statement will match against all
of the user's permission paths and clear the matched permission paths. For
example, if User A has read permission for `group1.company1.factory1`, when
revoking read permission for `group1.company1.**`, it will remove A's read
permission for `group1.company1.factory1`.
-```
-CREATE ROLE <roleName>;
-Eg: IoTDB > CREATE ROLE `admin`;
-```
-* Delete Role
-```
-DROP ROLE <roleName>;
-Eg: IoTDB > DROP ROLE `admin`;
-```
+## Authentication
-* Grant User Privileges
+User permissions mainly consist of three parts: permission scope (path),
permission type, and the "with grant option" flag:
```
-GRANT USER <userName> PRIVILEGES <privileges> ON <nodeNames>;
-Eg: IoTDB > GRANT USER `tempuser` PRIVILEGES INSERT_TIMESERIES,
DELETE_TIMESERIES on root.ln.**, root.sgcc.**;
-Eg: IoTDB > GRANT USER `tempuser` PRIVILEGES CREATE_ROLE;
+userTest1:
+ root.t1.** - read_schema, read_data - with grant option
+ root.** - write_schema, write_data - with grant option
```
-- Grant User All Privileges
+Each user has such a permission access list, identifying all the permissions
they have acquired. You can view their permissions by using the command `LIST
PRIVILEGES OF USER <username>`.
-```
-GRANT USER <userName> PRIVILEGES ALL;
-Eg: IoTDB > GRANT USER `tempuser` PRIVILEGES ALL;
-```
+When authorizing a path, the database will match the path with the
permissions. For example, when checking the read_schema permission for
`root.t1.t2`, it will first match with the permission access list `root.t1.**`.
If it matches successfully, it will then check if that path contains the
permission to be authorized. If not, it continues to the next path-permission
match until a match is found or all matches are exhausted.
-* Grant Role Privileges
+When performing authorization for multiple paths, such as executing a
multi-path query task, the database will only present data for which the user
has permissions. Data for which the user does not have permissions will not be
included in the results, and information about these paths without permissions
will be output to the alert messages.
-```
-GRANT ROLE <roleName> PRIVILEGES <privileges> ON <nodeNames>;
-Eg: IoTDB > GRANT ROLE `temprole` PRIVILEGES INSERT_TIMESERIES,
DELETE_TIMESERIES ON root.sgcc.**, root.ln.**;
-Eg: IoTDB > GRANT ROLE `temprole` PRIVILEGES CREATE_ROLE;
-```
+Please note that the following operations require checking multiple
permissions:
-- Grant Role All Privileges
+1. Enabling the automatic sequence creation feature requires not only write
permission for the corresponding sequence when a user inserts data into a
non-existent sequence but also metadata modification permission for the
sequence.
-```
-GRANT ROLE <roleName> PRIVILEGES ALL ON <nodeNames>;
-Eg: IoTDB > GRANT ROLE `temprole` PRIVILEGES ALL;
-```
+2. When executing the "select into" statement, it is necessary to check the
read permission for the source sequence and the write permission for the target
sequence. It should be noted that the source sequence data may only be
partially accessible due to insufficient permissions, and if the target
sequence has insufficient write permissions, an error will occur, terminating
the task.
-* Grant User Role
+3. View permissions and data source permissions are independent. Performing
read and write operations on a view will only check the permissions of the view
itself and will not perform permission validation on the source path.
-```
-GRANT <roleName> TO <userName>;
-Eg: IoTDB > GRANT `temprole` TO tempuser;
-```
-* Revoke User Privileges
+## Function Syntax and Examples
-```
-REVOKE USER <userName> PRIVILEGES <privileges> ON <nodeNames>;
-Eg: IoTDB > REVOKE USER `tempuser` PRIVILEGES DELETE_TIMESERIES on root.ln.**;
-Eg: IoTDB > REVOKE USER `tempuser` PRIVILEGES CREATE_ROLE;
-```
+IoTDB provides composite permissions for user authorization:
-* Revoke User All Privileges
+| Permission Name | Permission Scope |
+|-----------------|--------------------------|
+| ALL | All permissions |
+| READ | READ_SCHEMA, READ_DATA |
+| WRITE | WRITE_SCHEMA, WRITE_DATA |
-```
-REVOKE USER <userName> PRIVILEGES ALL;
-Eg: IoTDB > REVOKE USER `tempuser` PRIVILEGES ALL;
-```
+Composite permissions are not specific permissions themselves but a shorthand
way to denote a combination of permissions, with no difference from directly
specifying the corresponding permission names.
-* Revoke Role Privileges
+The following series of specific use cases will demonstrate the usage of
permission statements. Non-administrator users executing the following
statements require obtaining the necessary permissions, which are indicated
after the operation description.
-```
-REVOKE ROLE <roleName> PRIVILEGES <privileges> ON <nodeNames>;
-Eg: IoTDB > REVOKE ROLE `temprole` PRIVILEGES DELETE_TIMESERIES ON root.ln.**;
-Eg: IoTDB > REVOKE ROLE `temprole` PRIVILEGES CREATE_ROLE;
-```
+### User and Role Related
-* Revoke All Role Privileges
+- Create user (Requires MANAGE_USER permission)
-```
-REVOKE ROLE <roleName> PRIVILEGES ALL;
-Eg: IoTDB > REVOKE ROLE `temprole` PRIVILEGES ALL;
+```SQL
+CREATE USER <userName> <password>
+eg: CREATE USER user1 'passwd'
```
-* Revoke Role From User
+- Delete user (Requires MANAGE_USER permission)
-```
-REVOKE <roleName> FROM <userName>;
-Eg: IoTDB > REVOKE `temprole` FROM tempuser;
+```sql
+DROP USER <userName>
+eg: DROP USER user1
```
-* List Users
+- Create role (Requires MANAGE_ROLE permission)
-```
-LIST USER
-Eg: IoTDB > LIST USER
+```sql
+CREATE ROLE <roleName>
+eg: CREATE ROLE role1
```
-* List User of Specific Role
+- Delete role (Requires MANAGE_ROLE permission)
-```
-LIST USER OF ROLE <roleName>;
-Eg: IoTDB > LIST USER OF ROLE `roleuser`;
+```sql
+DROP ROLE <roleName>
+eg: DROP ROLE role1
```
-* List Roles
+- Grant role to user (Requires MANAGE_ROLE permission)
-```
-LIST ROLE
-Eg: IoTDB > LIST ROLE
+```sql
+GRANT ROLE <ROLENAME> TO <USERNAME>
+eg: GRANT ROLE admin TO user1
```
-* List Roles of Specific User
+- Revoke role from user(Requires MANAGE_ROLE permission)
-```
-LIST ROLE OF USER <username> ;
-Eg: IoTDB > LIST ROLE OF USER `tempuser`;
+```sql
+REVOKE ROLE <ROLENAME> FROM <USER>
+eg: REVOKE ROLE admin FROM user1
```
-* List All Privileges of Users
+- List all user (Requires MANAGE_USER permission)
-```
-LIST PRIVILEGES USER <username> ;
-Eg: IoTDB > LIST PRIVILEGES USER `tempuser`;
+```sql
+LIST USER
```
-* List Related Privileges of Users(On Specific Paths)
+- List all role (Requires MANAGE_ROLE permission)
-```
-LIST PRIVILEGES USER <username> ON <paths>;
-Eg: IoTDB> LIST PRIVILEGES USER `tempuser` ON root.ln.**, root.ln.wf01.**;
-+--------+-----------------------------------+
-| role| privilege|
-+--------+-----------------------------------+
-| | root.ln.** : ALTER_TIMESERIES|
-|temprole|root.ln.wf01.** : CREATE_TIMESERIES|
-+--------+-----------------------------------+
-Total line number = 2
-It costs 0.005s
-IoTDB> LIST PRIVILEGES USER `tempuser` ON root.ln.wf01.wt01.**;
-+--------+-----------------------------------+
-| role| privilege|
-+--------+-----------------------------------+
-| | root.ln.** : ALTER_TIMESERIES|
-|temprole|root.ln.wf01.** : CREATE_TIMESERIES|
-+--------+-----------------------------------+
-Total line number = 2
-It costs 0.005s
+```sql
+LIST ROLE
```
-* List All Privileges of Roles
+- List all users granted specific role.（Requires MANAGE_USER permission)
-```
-LIST PRIVILEGES ROLE <roleName>
-Eg: IoTDB > LIST PRIVILEGES ROLE `actor`;
+```sql
+LIST USER OF ROLE <roleName>
+eg: LIST USER OF ROLE roleuser
```
-* List Related Privileges of Roles(On Specific Paths)
-
-```
-LIST PRIVILEGES ROLE <roleName> ON <paths>;
-Eg: IoTDB> LIST PRIVILEGES ROLE `temprole` ON root.ln.**, root.ln.wf01.wt01.**;
-+-----------------------------------+
-| privilege|
-+-----------------------------------+
-|root.ln.wf01.** : CREATE_TIMESERIES|
-+-----------------------------------+
-Total line number = 1
-It costs 0.005s
-IoTDB> LIST PRIVILEGES ROLE `temprole` ON root.ln.wf01.wt01.**;
-+-----------------------------------+
-| privilege|
-+-----------------------------------+
-|root.ln.wf01.** : CREATE_TIMESERIES|
-+-----------------------------------+
-Total line number = 1
-It costs 0.005s
-```
+- List all role granted to specific user.
-* Alter Password
+ Users can list their own roles, but listing roles of other users requires
the MANAGE_ROLE permission.
+```sql
+LIST ROLE OF USER <username>
+eg: LIST ROLE OF USER tempuser
```
-ALTER USER <username> SET PASSWORD <password>;
-Eg: IoTDB > ALTER USER `tempuser` SET PASSWORD 'newpwd';
-```
-
-## Other Instructions
-
-### The Relationship among Users, Privileges and Roles
-
-A Role is a set of privileges, and privileges and roles are both attributes of
users. That is, a role can have several privileges and a user can have several
roles and privileges (called the user's own privileges).
-
-At present, there is no conflicting privilege in IoTDB, so the real privileges
of a user is the union of the user's own privileges and the privileges of the
user's roles. That is to say, to determine whether a user can perform an
operation, it depends on whether one of the user's own privileges or the
privileges of the user's roles permits the operation. The user's own privileges
and privileges of the user's roles may overlap, but it does not matter.
-
-It should be noted that if users have a privilege (corresponding to operation
A) themselves and their roles contain the same privilege, then revoking the
privilege from the users themselves alone can not prohibit the users from
performing operation A, since it is necessary to revoke the privilege from the
role, or revoke the role from the user. Similarly, revoking the privilege from
the users's roles alone can not prohibit the users from performing operation A.
-
-At the same time, changes to roles are immediately reflected on all users who
own the roles. For example, adding certain privileges to roles will immediately
give all users who own the roles corresponding privileges, and deleting certain
privileges will also deprive the corresponding users of the privileges (unless
the users themselves have the privileges).
-
-### List of Privileges Included in the System
-
-| privilege Name | Interpretation
| Example |
-| :------------------------ |
:----------------------------------------------------------- |
------------------------------------------------------------ |
-| CREATE\_DATABASE | create database; set/unset database ttl; path
dependent | Eg1: `CREATE DATABASE root.ln;`<br />Eg2:`set ttl to root.ln
3600000;`<br />Eg3:`unset ttl to root.ln;` |
-| DELETE\_DATABASE | delete databases; path dependent
| Eg: `delete database root.ln;` |
-| CREATE\_TIMESERIES | create timeseries; path dependent
| Eg1: create timeseries<br />`create timeseries
root.ln.wf02.status with datatype=BOOLEAN,encoding=PLAIN;`<br />Eg2: create
aligned timeseries<br />`create aligned timeseries root.ln.device1(latitude
FLOAT encoding=PLAIN compressor=SNAPPY, longitude FLOAT encoding=PLAIN
compressor=SNAPPY);` |
-| INSERT\_TIMESERIES | insert data; path dependent
| Eg1: `insert into root.ln.wf02(timestamp,status)
values(1,true);`<br />Eg2: `insert into root.sg1.d1(time, s1, s2) aligned
values(1, 1, 1)` |
-| ALTER\_TIMESERIES | alter timeseries; path dependent
| Eg1: `alter timeseries root.turbine.d1.s1 ADD TAGS tag3=v3,
tag4=v4;`<br />Eg2: `ALTER timeseries root.turbine.d1.s1 UPSERT ALIAS=newAlias
TAGS(tag2=newV2, tag3=v3) ATTRIBUTES(attr3=v3, attr4=v4);` |
-| READ\_TIMESERIES | query data; path dependent
| Eg1: `SHOW DATABASES;` <br />Eg2: `show child paths root.ln, show
child nodes root.ln;`<br />Eg3: `show devices;`<br />Eg4: `show timeseries
root.**;`<br />Eg5: `show schema templates;`<br />Eg6: `show all ttl`<br />Eg7:
[Query-Data](../Query-Data/Overview.md)（The query statements under this section
all use this permission）<br />Eg8: CVS format data export<br
/>`./export-csv.bat -h 127.0.0.1 -p 6 [...]
-| DELETE\_TIMESERIES | delete data or timeseries; path dependent
| Eg1: delete timeseries<br />`delete timeseries
root.ln.wf01.wt01.status`<br />Eg2: delete data<br />`delete from
root.ln.wf02.wt02.status where time < 10`<br />Eg3: use drop semantic<br
/>`drop timeseries root.ln.wf01.wt01.status |
-| CREATE\_USER | create users; path independent
| Eg: `create user thulab 'passwd';` |
-| DELETE\_USER | delete users; path independent
| Eg: `drop user xiaoming;` |
-| MODIFY\_PASSWORD | modify passwords for all users; path
independent; (Those who do not have this privilege can still change their own
asswords. ) | Eg: `alter user tempuser SET PASSWORD 'newpwd';` |
-| LIST\_USER | list all users; list all user of specific role;
list a user's related privileges on speciific paths; path independent | Eg1:
`list user;`<br />Eg2: `list user of role 'wirte_role';`<br />Eg3: `list
privileges user admin;`<br />Eg4: `list privileges user 'admin' on
root.sgcc.**;` |
-| GRANT\_USER\_PRIVILEGE | grant user privileges; path independent
| Eg: `grant user tempuser privileges DELETE_TIMESERIES on
root.ln.**;` |
-| REVOKE\_USER\_PRIVILEGE | revoke user privileges; path independent
| Eg: `revoke user tempuser privileges DELETE_TIMESERIES on
root.ln.**;` |
-| GRANT\_USER\_ROLE | grant user roles; path independent
| Eg: `grant temprole to tempuser;` |
-| REVOKE\_USER\_ROLE | revoke user roles; path independent
| Eg: `revoke temprole from tempuser;` |
-| CREATE\_ROLE | create roles; path independent
| Eg: `create role admin;` |
-| DELETE\_ROLE | delete roles; path independent
| Eg: `drop role admin;` |
-| LIST\_ROLE | list all roles; list all roles of specific user;
list a role's related privileges on speciific paths; path independent | Eg1:
`list role`<br />Eg2: `list role of user 'actor';`<br />Eg3: `list privileges
role wirte_role;`<br />Eg4: `list privileges role wirte_role ON root.sgcc;` |
-| GRANT\_ROLE\_PRIVILEGE | grant role privileges; path independent
| Eg: `grant role temprole privileges DELETE_TIMESERIES ON
root.ln.**;` |
-| REVOKE\_ROLE\_PRIVILEGE | revoke role privileges; path independent
| Eg: `revoke role temprole privileges DELETE_TIMESERIES ON
root.ln.**;` |
-| CREATE_FUNCTION | register UDFs; path independent
| Eg: `create function example AS
'org.apache.iotdb.udf.UDTFExample';` |
-| DROP_FUNCTION | deregister UDFs; path independent
| Eg: `drop function example` |
-| CREATE_TRIGGER | create triggers; path dependent
| Eg1: `CREATE TRIGGER <TRIGGER-NAME> BEFORE INSERT ON <FULL-PATH>
AS <CLASSNAME>`<br />Eg2: `CREATE TRIGGER <TRIGGER-NAME> AFTER INSERT ON
<FULL-PATH> AS <CLASSNAME>` |
-| DROP_TRIGGER | drop triggers; path dependent
| Eg: `drop trigger 'alert-listener-sg1d1s1'` |
-| CREATE_CONTINUOUS_QUERY | create continuous queries; path independent
| Eg: `CREATE CONTINUOUS QUERY cq1 RESAMPLE RANGE 40s BEGIN
<QUERY-BODY> END` |
-| DROP_CONTINUOUS_QUERY | drop continuous queries; path independent
| Eg1: `DROP CONTINUOUS QUERY cq3`<br />Eg2: `DROP CQ cq3` |
-| SHOW_CONTINUOUS_QUERIES | show continuous queries; path independent
| Eg1: `SHOW CONTINUOUS QUERIES`<br />Eg2: `SHOW cqs` |
-| UPDATE_TEMPLATE | create and drop schema template; path
independent | Eg1: `create schema template t1(s1 int32)`<br />Eg2:
`drop schema template t1` |
-| READ_TEMPLATE | show schema templates and show nodes in schema
template; path independent | Eg1: `show schema templates`<br/>Eg2: `show nodes
in template t1` |
-| APPLY_TEMPLATE | set, unset and activate schema template; path
dependent | Eg1: `set schema template t1 to root.sg.d`<br/>Eg2: `unset
schema template t1 from root.sg.d`<br/>Eg3: `create timeseries of schema
template on root.sg.d`<br/>Eg4: `delete timeseries of schema template on
root.sg.d` |
-| READ_TEMPLATE_APPLICATION | show paths set and using schema template; path
independent | Eg1: `show paths set schema template t1`<br/>Eg2: `show paths
using schema template t1` |
-
-Note that path dependent privileges can only be granted or revoked on root.**;
-
-Note that the following SQL statements need to be granted multiple permissions
before they can be used：
-
-- Import data: Need to assign `READ_TIMESERIES`，`INSERT_TIMESERIES` two
permissions.。
+- List all privileges of user
-```
-Eg: IoTDB > ./import-csv.bat -h 127.0.0.1 -p 6667 -u renyuhua -pw root -f
dump0.csv
-```
-
-- Query Write-back (SELECT INTO)
-- - `READ_TIMESERIES` permission of source sequence in all `select` clauses
is required
-- `INSERT_TIMESERIES` permission of target sequence in all `into` clauses is
required
+Users can list their own privileges, but listing privileges of other users
requires the MANAGE_USER permission.
-```
-Eg: IoTDB > select s1, s1 into t1, t2 from root.sg.d1 limit 5 offset 1000
+```sql
+LIST PRIVILEGES OF USER <username>;
+eg: LIST PRIVILEGES OF USER tempuser;
```
-### Username Restrictions
+- List all privileges of role
-IoTDB specifies that the character length of a username should not be less
than 4, and the username cannot contain spaces.
+Users can list the permission information of roles they have, but listing
permissions of other roles requires the MANAGE_ROLE permission.
-### Password Restrictions
-
-IoTDB specifies that the character length of a password should have no less
than 4 character length, and no spaces. The password is encrypted with MD5.
-
-### Role Name Restrictions
-
-IoTDB specifies that the character length of a role name should have no less
than 4 character length, and no spaces.
-
-### Path pattern in Administration Management
+```sql
+LIST PRIVILEGES OF ROLE <roleName>;
+eg: LIST PRIVILEGES OF ROLE actor;
+```
-A path pattern's result set contains all the elements of its sub pattern's
-result set. For example, `root.sg.d.*` is a sub pattern of
-`root.sg.*.*`, while `root.sg.**` is not a sub pattern of
-`root.sg.*.*`. When a user is granted privilege on a pattern, the pattern used
in his DDL or DML must be a sub pattern of the privilege pattern, which
guarantees that the user won't access the timeseries exceed his privilege scope.
+- Update password
-### Permission cache
+Users can update their own password, but updating passwords of other users
requires the MANAGE_USER permission.
-In distributed related permission operations, when changing permissions other
than creating users and roles, all the cache information of `dataNode` related
to the user (role) will be cleared first. If any `dataNode` cache information
is clear and fails, the permission change task will fail.
+```sql
+ALTER USER <username> SET PASSWORD <password>;
+eg: ALTER USER tempuser SET PASSWORD 'newpwd';
+```
-### Operations restricted by non root users
+### Authorization and Deauthorization
-At present, the following SQL statements supported by iotdb can only be
operated by the `root` user, and no corresponding permission can be given to
the new user.
+Users can use authorization statements to grant permissions to other users.
The syntax is as follows:
-#### TsFile Management
+```sql
+GRANT <PRIVILEGES> ON <PATHS> TO ROLE/USER <NAME> [WITH GRANT OPTION]；
+eg: GRANT READ ON root.** TO ROLE role1;
+eg: GRANT READ_DATA, WRITE_DATA ON root.t1.** TO USER user1;
+eg: GRANT READ_DATA, WRITE_DATA ON root.t1.**,root.t2.** TO USER user1;
+eg: GRANT MANAGE_ROLE ON root.** TO USER user1 WITH GRANT OPTION;
+eg: GRANT ALL ON root.** TO USER user1 WITH GRANT OPTION;
+```
-- Load TsFiles
+Users can use deauthorization statements to revoke permissions from others.
The syntax is as follows:
-```
-Eg: IoTDB > load '/Users/Desktop/data/1575028885956-101-0.tsfile'
+```sql
+REVOKE <PRIVILEGES> ON <PATHS> FROM ROLE/USER <NAME>;
+eg: REVOKE READ ON root.** FROM ROLE role1;
+eg: REVOKE READ_DATA, WRITE_DATA ON root.t1.** FROM USER user1;
+eg: REVOKE READ_DATA, WRITE_DATA ON root.t1.**, root.t2.** FROM USER user1;
+eg: REVOKE MANAGE_ROLE ON root.** FROM USER user1;
+eg: REVOKE ALL ON ROOT.** FROM USER user1;
+```
+
+- **When non-administrator users execute authorization/deauthorization
statements, they need to have \<PRIVILEGES\> permissions on \<PATHS\>, and
these permissions must be marked with WITH GRANT OPTION.**
+
+- When granting or revoking global permissions or when the statement contains
global permissions (expanding ALL includes global permissions), you must
specify the path as root**. For example, the following
authorization/deauthorization statements are valid:
+
+ ```sql
+ GRANT MANAGE_USER ON root.** TO USER user1;
+ GRANT MANAGE_ROLE ON root.** TO ROLE role1 WITH GRANT OPTION;
+ GRANT ALL ON root.** TO role role1 WITH GRANT OPTION;
+ REVOKE MANAGE_USER ON root.** FROM USER user1;
+ REVOKE MANAGE_ROLE ON root.** FROM ROLE role1;
+ REVOKE ALL ON root.** FROM ROLE role1;
+ ```
+
+ The following statements are invalid:
+
+ ```sql
+ GRANT READ, MANAGE_ROLE ON root.t1.** TO USER user1;
+ GRANT ALL ON root.t1.t2 TO USER user1 WITH GRANT OPTION;
+ REVOKE ALL ON root.t1.t2 FROM USER user1;
+ REVOKE READ, MANAGE_ROLE ON root.t1.t2 FROM ROLE ROLE1;
+ ```
+
+- \<PATH\> must be a full path or a matching path ending with a double
wildcard. The following paths are valid:
+
+ ```sql
+ root.**
+ root.t1.t2.**
+ root.t1.t2.t3
+ ```
+
+ The following paths are invalid:
+
+ ```sql
+ root.t1.*
+ root.t1.**.t2
+ root.t1*.t2.t3
+ ```
+
+
+
+## Examples
+
+ Based on the described [sample
data](https://github.com/thulab/iotdb/files/4438687/OtherMaterial-Sample.Data.txt),
IoTDB's sample data may belong to different power generation groups such as
ln, sgcc, and so on. Different power generation groups do not want other groups
to access their database data, so we need to implement data isolation at the
group level.
+
+#### Create Users
+Use `CREATE USER <userName> <password>` to create users. For example, we can
create two users for the ln and sgcc groups with the root user, who has all
permissions, and name them ln_write_user and sgcc_write_user. It is recommended
to enclose the username in backticks. The SQL statements are as follows:
+```SQL
+CREATE USER `ln_write_user` 'write_pwd'
+CREATE USER `sgcc_write_user` 'write_pwd'
```
-- remove a tsfile
+Now, using the SQL statement to display users:
-```
-Eg: IoTDB > remove
'/Users/Desktop/data/data/root.vehicle/0/0/1575028885956-101-0.tsfile'
+```sql
+LIST USER
```
-- unload a tsfile and move it to a target directory
+We can see that these two users have been created, and the result is as
follows:
-```
-Eg: IoTDB > unload
'/Users/Desktop/data/data/root.vehicle/0/0/1575028885956-101-0.tsfile'
'/data/data/tmp'
+```sql
+IoTDB> CREATE USER `ln_write_user` 'write_pwd'
+Msg: The statement is executed successfully.
+IoTDB> CREATE USER `sgcc_write_user` 'write_pwd'
+Msg: The statement is executed successfully.
+IoTDB> LIST USER;
++---------------+
+| user|
++---------------+
+| ln_write_user|
+| root|
+|sgcc_write_user|
++---------------+
+Total line number = 3
+It costs 0.012s
```
-#### Delete Time Partition (experimental)
+#### Granting Permissions to Users
-```
-Eg: IoTDB > DELETE PARTITION root.ln 0,1,2
+At this point, although two users have been created, they do not have any
permissions, so they cannot operate on the database. For example, if we use the
ln_write_user to write data to the database, the SQL statement is as follows:
+
+```sql
+INSERT INTO root.ln.wf01.wt01(timestamp,status) values(1509465600000,true)
```
-#### Continuous Query,CQ
+At this point, the system does not allow this operation, and an error is
displayed:
-```
-Eg: IoTDB > CREATE CONTINUOUS QUERY cq1 BEGIN SELECT max_value(temperature)
INTO temperature_max FROM root.ln.*.* GROUP BY time(10s) END
+```sql
+IoTDB> INSERT INTO root.ln.wf01.wt01(timestamp,status)
values(1509465600000,true)
+Msg: 803: No permissions for this operation, please add privilege WRITE_DATA
on [root.ln.wf01.wt01.status]
```
-#### Maintenance Command
+Now, we will grant each user write permissions to the corresponding paths
using the root user.
-- FLUSH
+We use the `GRANT <PRIVILEGES> ON <PATHS> TO USER <username>` statement to
grant permissions to users, for example:
-```
-Eg: IoTDB > flush
+```sql
+GRANT WRITE_DATA ON root.ln.** TO USER `ln_write_user`
+GRANT WRITE_DATA ON root.sgcc1.**, root.sgcc2.** TO USER `sgcc_write_user`
```
-- MERGE
+The execution status is as follows:
-```
-Eg: IoTDB > MERGE
-Eg: IoTDB > FULL MERGE
+```sql
+IoTDB> GRANT WRITE_DATA ON root.ln.** TO USER `ln_write_user`
+Msg: The statement is executed successfully.
+IoTDB> GRANT WRITE_DATA ON root.sgcc1.**, root.sgcc2.** TO USER
`sgcc_write_user`
+Msg: The statement is executed successfully.
```
-- CLEAR CACHE
+Then, using ln_write_user, try to write data again:
```sql
-Eg: IoTDB > CLEAR CACHE
+IoTDB> INSERT INTO root.ln.wf01.wt01(timestamp, status) values(1509465600000,
true)
+Msg: The statement is executed successfully.
```
-- SET SYSTEM TO READONLY / WRITABLE
+#### Revoking User Permissions
-```
-Eg: IoTDB > SET SYSTEM TO READONLY / WRITABLE
-```
+After granting user permissions, we can use the `REVOKE <PRIVILEGES> ON
<PATHS> FROM USER <USERNAME>` to revoke the permissions granted to users. For
example, using the root user to revoke the permissions of ln_write_user and
sgcc_write_user:
-- Query abort
-
-```
-Eg: IoTDB > KILL QUERY 1
+```sql
+REVOKE WRITE_DATA ON root.ln.** FROM USER `ln_write_user`
+REVOKE WRITE_DATA ON root.sgcc1.**, root.sgcc2.** FROM USER `sgcc_write_user`
```
-#### Watermark Tool
-- Watermark new users
+The execution status is as follows:
-```
-Eg: IoTDB > grant watermark_embedding to Alice
+```sql
+IoTDB> REVOKE WRITE_DATA ON root.ln.** FROM USER `ln_write_user`
+Msg: The statement is executed successfully.
+IoTDB> REVOKE WRITE_DATA ON root.sgcc1.**, root.sgcc2.** FROM USER
`sgcc_write_user`
+Msg: The statement is executed successfully.
```
-- Watermark Detection
-
-```
-Eg: IoTDB > revoke watermark_embedding from Alice
-```
+After revoking the permissions, ln_write_user no longer has the permission to
write data to root.ln.**:
+```sql
+IoTDB> INSERT INTO root.ln.wf01.wt01(timestamp, status) values(1509465600000,
true)
+Msg: 803: No permissions for this operation, please add privilege WRITE_DATA
on [root.ln.wf01.wt01.status]
+```
+
+## Other Explanations
+
+Roles are collections of permissions, and both permissions and roles are
attributes of users. In other words, a role can have multiple permissions, and
a user can have multiple roles and permissions (referred to as the user's
self-permissions).
+
+Currently, in IoTDB, there are no conflicting permissions. Therefore, the
actual permissions a user has are the union of their self-permissions and the
permissions of all their roles. In other words, to determine if a user can
perform a certain operation, it's necessary to check whether their
self-permissions or the permissions of all their roles allow that operation.
Self-permissions, role permissions, and the permissions of multiple roles a
user has may contain the same permission, but [...]
+
+It's important to note that if a user has a certain permission (corresponding
to operation A) on their own, and one of their roles has the same permission,
revoking the permission from the user alone will not prevent the user from
performing operation A. To prevent the user from performing operation A, you
need to revoke the permission from both the user and the role, or remove the
user from the role that has the permission. Similarly, if you only revoke the
permission from the role, it [...]
+
+At the same time, changes to roles will be immediately reflected in all users
who have that role. For example, adding a certain permission to a role will
immediately grant that permission to all users who have that role, and removing
a certain permission will cause those users to lose that permission (unless the
user has it on their own).
+
+
+
+## Upgrading from a previous version
+
+Before version 1.3, there were many different permission types. In 1.3
version's implementation, we have streamlined the permission types.
+
+The permission paths in version 1.3 of the database must be either full paths
or matching paths ending with a double wildcard. During system upgrades, any
invalid permission paths and permission types will be automatically converted.
The first invalid node on the path will be replaced with "**", and any
unsupported permission types will be mapped to the permissions supported by the
current system.
+
+| Permission | Path | Mapped-Permission | Mapped-path |
+|-------------------|-----------------|-------------------|---------------|
+| CREATE_DATBASE | root.db.t1.* | MANAGE_DATABASE | root.** |
+| INSERT_TIMESERIES | root.db.t2.*.t3 | WRITE_DATA | root.db.t2.** |
+| CREATE_TIMESERIES | root.db.t2*c.t3 | WRITE_SCHEMA | root.db.** |
+| LIST_ROLE | root.** | (ignore) | |
+
+
+
+You can refer to the table below for a comparison of permission types between
the old and new versions (where "--IGNORE" indicates that the new version
ignores that permission):
+
+| Permission Name | Path-Related | New Permission Name |
Path-Related |
+|---------------------------|--------------|---------------------|--------------|
+| CREATE_DATABASE | YES | MANAGE_DATABASE | NO
|
+| INSERT_TIMESERIES | YES | WRITE_DATA | YES
|
+| UPDATE_TIMESERIES | YES | WRITE_DATA | YES
|
+| READ_TIMESERIES | YES | READ_DATA | YES
|
+| CREATE_TIMESERIES | YES | WRITE_SCHEMA | YES
|
+| DELETE_TIMESERIES | YES | WRITE_SCHEMA | YES
|
+| CREATE_USER | NO | MANAGE_USER | NO
|
+| DELETE_USER | NO | MANAGE_USER | NO
|
+| MODIFY_PASSWORD | NO | -- IGNORE |
|
+| LIST_USER | NO | -- IGNORE |
|
+| GRANT_USER_PRIVILEGE | NO | -- IGNORE |
|
+| REVOKE_USER_PRIVILEGE | NO | -- IGNORE |
|
+| GRANT_USER_ROLE | NO | MANAGE_ROLE | NO
|
+| REVOKE_USER_ROLE | NO | MANAGE_ROLE | NO
|
+| CREATE_ROLE | NO | MANAGE_ROLE | NO
|
+| DELETE_ROLE | NO | MANAGE_ROLE | NO
|
+| LIST_ROLE | NO | -- IGNORE |
|
+| GRANT_ROLE_PRIVILEGE | NO | -- IGNORE |
|
+| REVOKE_ROLE_PRIVILEGE | NO | -- IGNORE |
|
+| CREATE_FUNCTION | NO | USE_UDF | NO
|
+| DROP_FUNCTION | NO | USE_UDF | NO
|
+| CREATE_TRIGGER | YES | USE_TRIGGER | NO
|
+| DROP_TRIGGER | YES | USE_TRIGGER | NO
|
+| START_TRIGGER | YES | USE_TRIGGER | NO
|
+| STOP_TRIGGER | YES | USE_TRIGGER | NO
|
+| CREATE_CONTINUOUS_QUERY | NO | USE_CQ | NO
|
+| DROP_CONTINUOUS_QUERY | NO | USE_CQ | NO
|
+| ALL | NO | All privilegs |
|
+| DELETE_DATABASE | YES | MANAGE_DATABASE | NO
|
+| ALTER_TIMESERIES | YES | WRITE_SCHEMA | YES
|
+| UPDATE_TEMPLATE | NO | -- IGNORE |
|
+| READ_TEMPLATE | NO | -- IGNORE |
|
+| APPLY_TEMPLATE | YES | WRITE_SCHEMA | YES
|
+| READ_TEMPLATE_APPLICATION | NO | -- IGNORE |
|
+| SHOW_CONTINUOUS_QUERIES | NO | -- IGNORE |
|
+| CREATE_PIPEPLUGIN | NO | USE_PIPE | NO
|
+| DROP_PIPEPLUGINS | NO | USE_PIPE | NO
|
+| SHOW_PIPEPLUGINS | NO | -- IGNORE |
|
+| CREATE_PIPE | NO | USE_PIPE | NO
|
+| START_PIPE | NO | USE_PIPE | NO
|
+| STOP_PIPE | NO | USE_PIPE | NO
|
+| DROP_PIPE | NO | USE_PIPE | NO
|
+| SHOW_PIPES | NO | -- IGNORE |
|
+| CREATE_VIEW | YES | WRITE_SCHEMA | YES
|
+| ALTER_VIEW | YES | WRITE_SCHEMA | YES
|
+| RENAME_VIEW | YES | WRITE_SCHEMA | YES
|
+| DELETE_VIEW | YES | WRITE_SCHEMA | YES
|
diff --git a/src/zh/UserGuide/Master/User-Manual/Authority-Management.md
b/src/zh/UserGuide/Master/User-Manual/Authority-Management.md
index 18be398..ec4cfb9 100644
--- a/src/zh/UserGuide/Master/User-Manual/Authority-Management.md
+++ b/src/zh/UserGuide/Master/User-Manual/Authority-Management.md
@@ -7,9 +7,9 @@
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
@@ -22,7 +22,7 @@
# 权限管理
IoTDB 为用户提供了权限管理操作，为用户提供对数据与集群系统的权限管理功能，保障数据与系统安全。
-本篇介绍IoTDB 中权限模块的基本概念、用户定义、权限管理、鉴权逻辑与功能用例，详细的 SQL 语句及使用方式详情请参见本文
[数据模式与概念章节](../Basic-Concept/Data-Model-and-Terminology.md)。同时，在 JAVA
编程环境中，您可以使用 [JDBC API](../API/Programming-JDBC.md) 单条或批量执行权限管理类语句。
+本篇介绍IoTDB 中权限模块的基本概念、用户定义、权限管理、鉴权逻辑与功能用例。在 JAVA 编程环境中，您可以使用 [JDBC
API](../API/Programming-JDBC.md) 单条或批量执行权限管理类语句。
## 基本概念
@@ -32,7 +32,7 @@ IoTDB 为用户提供了权限管理操作，为用户提供对数据与集群
### 权限
-数据库提供多种操作，但并非所有的用户都能执行所有操作。如果一个用户可以执行某项操作，则称该用户有执行该操作的权限。权限通常需要一个路径来西安限定其生效范围，可以使用[路径模式](../Basic-Concept/Data-Model-and-Terminology.md)灵活管理权限。
+数据库提供多种操作，但并非所有的用户都能执行所有操作。如果一个用户可以执行某项操作，则称该用户有执行该操作的权限。权限通常需要一个路径来限定其生效范围，可以使用[路径模式](../Basic-Concept/Data-Model-and-Terminology.md)灵活管理权限。
### 角色
@@ -46,7 +46,7 @@ IoTDB 为用户提供了权限管理操作，为用户提供对数据与集群
## 用户定义
-拥有 MANAGE_USER、MANAGE_ROLE 的用户或者管理员可以创建用户或者角色，创建用户需要满足以下约束。
+拥有 MANAGE_USER、MANAGE_ROLE 的用户或者管理员可以创建用户或者角色，需要满足以下约束：
### 用户名限制
@@ -74,12 +74,12 @@ IoTDB 主要有两类权限：序列权限、全局权限。
下表描述了这类权限的种类与范围：
-| 权限名称 | 权限范围
| 描述
|
-| ------------
|--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
-| READ_DATA | - select data
| 允许读取授权路径下的序列数据。
|
-| WRITE_DATA | - READ_DATA 包含的所有权限<br>- insert/delete data<br/>- Load
tsfile/import csv <br/>
|
允许读取授权路径下的序列数据。<br/>允许插入、删除授权路径下的的序列数据。<br/>允许在授权路径下导入、加载数据，在导入数据时，需要拥有对应路径的
WRITE_DATA 权限，在自动创建序列或数据库时，需要有 MANAGE_DATABASE 与 WRITE_SCHEMA 权限。
|
-| READ_SCHEMA | - show/count database<br/>- show/count child path<br/>-
show/count child node<br/>- show/count device<br/>- show/count timeseries<br/>-
show template<br/>- show view<br/>- show ttl |
允许获取授权路径下元数据树的详细信息：<br/>包括：路径下的数据库、子路径、子节点、设备、序列、模版、视图等。
|
-| WRITE_SCHEMA | - READ_SCHEMA 包含的权限<br/>- create/delete/alter
timeseries<br/>- create/set/unset/drop template<br/>- create/alter/delete
view<br/>- set ttl、unset ttl |
允许获取授权路径下元数据树的详细信息。<br/>允许在授权路径下对序列、模版、视图等进行创建、删除、修改操作。<br/>在创建或修改 view 的时候，会检查
view 路径的 WRITE_SCHEMA 权限、数据源的 READ_SCHEMA 权限。<br/>在对 view 进行查询、插入时，会检查 view 路径的
READ_DATA 权限、WRITE_DATA 权限。<br/>允许在授权路径下设置、取消、查看TTL。<br/> 允许在授权路径下挂载或者接触挂载模板。 |
+| 权限名称 | 描述
|
+|--------------|-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
+| READ_DATA | 允许读取授权路径下的序列数据。
|
+| WRITE_DATA |
允许读取授权路径下的序列数据。<br/>允许插入、删除授权路径下的的序列数据。<br/>允许在授权路径下导入、加载数据，在导入数据时，需要拥有对应路径的
WRITE_DATA 权限，在自动创建数据库与序列时，需要有 MANAGE_DATABASE 与 WRITE_SCHEMA 权限。
|
+| READ_SCHEMA | 允许获取授权路径下元数据树的详细信息：<br/>包括：路径下的数据库、子路径、子节点、设备、序列、模版、视图等。
|
+| WRITE_SCHEMA |
允许获取授权路径下元数据树的详细信息。<br/>允许在授权路径下对序列、模版、视图等进行创建、删除、修改操作。<br/>在创建或修改 view 的时候，会检查
view 路径的 WRITE_SCHEMA 权限、数据源的 READ_SCHEMA 权限。<br/>在对 view 进行查询、插入时，会检查 view 路径的
READ_DATA 权限、WRITE_DATA 权限。<br/>允许在授权路径下设置、取消、查看TTL。<br/> 允许在授权路径下挂载或者接触挂载模板。 |
### 全局权限
@@ -87,24 +87,23 @@ IoTDB 主要有两类权限：序列权限、全局权限。
下表描述了系统权限的种类：
-| 权限名称 | 权限范围
| 描述
|
-| :-------------:
|:-------------------------------------------------------------------------------------------------------------------|--------------------------------------------------------------------------------------|
-| MANAGE_DATABASE | - create/delete database
| 允许用户创建、删除数据库。
|
-| MANAGE_USER | - create/delete/alter/list user
| 允许用户创建、删除、修改、查看用户。
|
-| MANAGE_ROLE | - create/delete/list role<br/>- grant/revoke role to/from
user | 允许用户创建、删除、修改、查看角色。
<br/> 允许用户将角色授予给其他用户 |
-| USE_TRIGGER | - create/drop/show trigger
|
允许用户创建、删除、查看触发器。<br/>与触发器的数据源权限检查相独立。
|
-| USE_UDF | - create/drop/show function
|
允许用户创建、删除、查看用户自定义函数。<br/>与自定义函数的数据源权限检查相独立。
|
-| USE_CQ | - create/drop/show continuous queries
|
允许用户创建、删除、查看连续查询。<br/>与连续查询的数据源权限检查相独立。
|
-| USE_PIPE | - create/start/stop/drop/show pipe<br/>- create/drop/show
pipeplugin |
允许用户创建、开始、停止、删除、查看管道。<br/>允许用户创建、删除、查看管道插件。<br/>与管道的数据源权限检查相独立。
|
-| EXTEND_TEMPLATE | - extend schema template
| 自动创建模板权限。
|
-| MAINTAIN | - kill query <br/>- show queries<br/>- show
variables<br/>- show cluster (details) |
允许用户查询、取消查询。 <br/> 允许用户查看变量。 <br/> 允许用户查看集群状态。
|
-| -（仅root） | - flush<br/>- merge<br/>- clear cache<br/>- set system to
readonly/running<br/>- create/drop/alter schema template |
管理员权限独占。<br/>集群的运维管理权限。<br/> 创建、删除、修改、挂载、卸载元数据模板。<br/>
这类操作只有管理员可以执行，并无对应的权限课授予其他用户。 |
+| 权限名称 | 描述
|
+|:---------------:|:------------------------------------------------------------------|
+| MANAGE_DATABASE | - 允许用户创建、删除数据库.
|
+| MANAGE_USER | - 允许用户创建、删除、修改、查看用户。
|
+| MANAGE_ROLE | - 允许用户创建、删除、查看角色。 <br/> 允许用户将角色授予给其他用户,或取消其他用户的角色。
|
+| USE_TRIGGER | - 允许用户创建、删除、查看触发器。<br/>与触发器的数据源权限检查相独立。
|
+| USE_UDF | - 允许用户创建、删除、查看用户自定义函数。<br/>与自定义函数的数据源权限检查相独立。
|
+| USE_CQ | -
允许用户创建、开始、停止、删除、查看管道。<br/>允许用户创建、删除、查看管道插件。<br/>与管道的数据源权限检查相独立。 |
+| EXTEND_TEMPLATE | - 允许自动扩展模板。
|
+| MAINTAIN | - 允许用户查询、取消查询。 <br/> 允许用户查看变量。 <br/> 允许用户查看集群状态。
|
+| USE_MODEL | - 允许用户创建、删除、查询深度学习模型
|
关于模板权限：
1. 模板的创建、删除、修改、查询、挂载、卸载仅允许管理员操作。
2. 激活模板需要拥有激活路径的 WRITE_SCHEMA 权限
-3. 若开启了自动创建，在向挂载了模板的不存在路径写入时，数据库会自动创建该路径与模板，因此需要有 EXTEND_TEMPLATE 权限与写入序列的
WRITE_DATA 权限。
+3. 若开启了自动创建，在向挂载了模板的不存在路径写入时，数据库会自动扩展模板并写入数据，因此需要有 EXTEND_TEMPLATE 权限与写入序列的
WRITE_DATA 权限。
4. 解除模板，需要拥有挂载模板路径的 WRITE_SCHEMA 权限。
5. 查询使用了某个元数据模板的路径，需要有路径的 READ_SCHEMA 权限，否则将返回为空。
@@ -142,18 +141,24 @@ userTest1 :
在对一个路径进行鉴权时，数据库会进行路径与权限的匹配。例如检查 `root.t1.t2` 的 read_schema 权限时，首先会与权限访问列表的
`root.t1.**`进行匹配，匹配成功，则检查该路径是否包含待鉴权的权限，否则继续下一条路径-权限的匹配，直到匹配成功或者匹配结束。
-在进行多路径鉴权时，例如执行一个多路径查询的任务，数据库只会将有权限的数据呈现出来，无权限的数据不会包含在结果中，这些无权限的路径信息最后会输出到报警信息中。
+在进行多路径鉴权时，对于多路径查询任务，数据库只会将有权限的数据呈现出来，无权限的数据不会包含在结果中；对于多路径写入任务，数据库要求必须所有的目标序列都获得了对应的权限，才能进行写入。
+
+请注意，下面的操作需要检查多重权限
+1. 开启了自动创建序列功能，在用户将数据插入到不存在的序列中时，不仅需要对应序列的写入权限，还需要序列的元数据修改权限。
+2. 执行 select into
语句时，需要检查源序列的读权限与目标序列的写权限。需要注意的是源序列数据可能因为权限不足而仅能获取部分数据，目标序列写入权限不足时会报错终止任务。
+3. View 权限与数据源的权限是独立的，向 view 执行读写操作仅会检查 view 的权限，而不再对源路径进行权限校验。
+
## 功能语法与示例
IoTDB 提供了组合权限，方便用户授权：
-| 权限名称 | 权限范围 |
-| -------- | ---------------------------------- |
-| ALL | 所有权限（除管理员用户独占的权限） |
-| READ | READ_SCHEMA、READ_DATA |
-| WRITE | WRITE_SCHEMA、WRITE_DATA |
+| 权限名称 | 权限范围 |
+|-------|-------------------------|
+| ALL | 所有权限 |
+| READ | READ_SCHEMA、READ_DATA |
+| WRITE | WRITE_SCHEMA、WRITE_DATA |
组合权限并不是一种具体的权限，而是一种简写方式，与直接书写对应的权限名称没有差异。
@@ -293,8 +298,8 @@ eg: REVOKE ALL ON ROOT.** FROM USER user1;
- 在授予取消全局权限时，或者语句中包含全局权限时(ALL 展开会包含全局权限），须指定 path 为 root.**。
例如，以下授权/取消授权语句是合法的：
```SQL
- GRANT MANAGE_USER ON root.** FROM USER user1;
- GRANT MANAGE_ROLE ON root.** to ROLE role1 WITH GRANT OPTION;
+ GRANT MANAGE_USER ON root.** TO USER user1;
+ GRANT MANAGE_ROLE ON root.** TO ROLE role1 WITH GRANT OPTION;
GRANT ALL ON root.** TO role role1 WITH GRANT OPTION;
REVOKE MANAGE_USER ON root.** FROM USER user1;
REVOKE MANAGE_ROLE ON root.** FROM ROLE role1;
@@ -310,7 +315,7 @@ eg: REVOKE ALL ON ROOT.** FROM USER user1;
```
- \<PATH\> 必须为全路径或者以双通配符结尾的匹配路径，以下路径是合法的:
-
+
```SQL
root.**
root.t1.t2.**
@@ -325,11 +330,11 @@ eg: REVOKE ALL ON ROOT.** FROM USER user1;
root.t1*.t2.t3
```
-### 示例
+## 示例
根据本文中描述的
[样例数据](https://github.com/thulab/iotdb/files/4438687/OtherMaterial-Sample.Data.txt)
内容，IoTDB 的样例数据可能同时属于 ln, sgcc
等不同发电集团，不同的发电集团不希望其他发电集团获取自己的数据库数据，因此我们需要将不同的数据在集团层进行权限隔离。
-#### 创建用户
+### 创建用户
使用 `CREATE USER <userName> <password>` 创建用户。例如，我们可以使用具有所有权限的root用户为 ln 和 sgcc
集团创建两个用户角色，名为 ln_write_user, sgcc_write_user，密码均为 write_pwd。建议使用反引号(`)包裹用户名。SQL
语句为：
@@ -362,7 +367,7 @@ Total line number = 3
It costs 0.012s
```
-#### 赋予用户权限
+### 赋予用户权限
此时，虽然两个用户已经创建，但是他们不具有任何权限，因此他们并不能对数据库进行操作，例如我们使用 ln_write_user
用户对数据库中的数据进行写入，SQL 语句为：
@@ -401,7 +406,7 @@ IoTDB> INSERT INTO root.ln.wf01.wt01(timestamp, status)
values(1509465600000, tr
Msg: The statement is executed successfully.
```
-#### 撤销用户权限
+### 撤销用户权限
授予用户权限后，我们可以使用 `REVOKE <PRIVILEGES> ON <PATHS> FROM USER
<USERNAME>`来撤销已经授予用户的权限。例如，用root用户撤销ln_write_user和sgcc_write_user的权限：
``` SQL
@@ -432,4 +437,73 @@ Msg: 803: No permissions for this operation, please add
privilege WRITE_DATA on
需要注意的是：如果一个用户自身有某种权限（对应操作 A），而他的某个角色有相同的权限。那么如果仅从该用户撤销该权限无法达到禁止该用户执行操作 A
的目的，还需要从这个角色中也撤销对应的权限，或者从这个用户将该角色撤销。同样，如果仅从上述角色将权限撤销，也不能禁止该用户执行操作 A。
-同时，对角色的修改会立即反映到所有拥有该角色的用户上，例如对角色增加某种权限将立即使所有拥有该角色的用户都拥有对应权限，删除某种权限也将使对应用户失去该权限（除非用户本身有该权限）。
\ No newline at end of file
+同时，对角色的修改会立即反映到所有拥有该角色的用户上，例如对角色增加某种权限将立即使所有拥有该角色的用户都拥有对应权限，删除某种权限也将使对应用户失去该权限（除非用户本身有该权限）。
+
+## 升级说明
+
+在 1.3 版本前，权限类型较多，在这一版实现中，权限类型做了精简，并且添加了对权限路径的约束。
+
+数据库 1.3 版本的权限路径必须为全路径或者以双通配符结尾的匹配路径，在系统升级时，会自动转换不合法的权限路径和权限类型。
+路径上首个非法节点会被替换为`**`, 不在支持的权限类型也会映射到当前系统支持的权限上。
+
+例如：
+
+| 权限类型 | 权限路径 | 映射之后的权限类型 | 权限路径 |
+| ----------------- | --------------- |-----------------| ------------- |
+| CREATE_DATBASE | root.db.t1.* | MANAGE_DATABASE | root.** |
+| INSERT_TIMESERIES | root.db.t2.*.t3 | WRITE_DATA | root.db.t2.** |
+| CREATE_TIMESERIES | root.db.t2*c.t3 | WRITE_SCHEMA | root.db.** |
+| LIST_ROLE | root.** | (忽略) | |
+
+
+新旧版本的权限类型对照可以参照下面的表格（--IGNORE 表示新版本忽略该权限）：
+
+| 权限名称 | 是否路径相关 | 新权限名称 | 是否路径相关 |
+|---------------------------|--------|-----------------|--------|
+| CREATE_DATABASE | 是 | MANAGE_DATABASE | 否 |
+| INSERT_TIMESERIES | 是 | WRITE_DATA | 是 |
+| UPDATE_TIMESERIES | 是 | WRITE_DATA | 是 |
+| READ_TIMESERIES | 是 | READ_DATA | 是 |
+| CREATE_TIMESERIES | 是 | WRITE_SCHEMA | 是 |
+| DELETE_TIMESERIES | 是 | WRITE_SCHEMA | 是 |
+| CREATE_USER | 否 | MANAGE_USER | 否 |
+| DELETE_USER | 否 | MANAGE_USER | 否 |
+| MODIFY_PASSWORD | 否 | -- IGNORE | |
+| LIST_USER | 否 | -- IGNORE | |
+| GRANT_USER_PRIVILEGE | 否 | -- IGNORE | |
+| REVOKE_USER_PRIVILEGE | 否 | -- IGNORE | |
+| GRANT_USER_ROLE | 否 | MANAGE_ROLE | 否 |
+| REVOKE_USER_ROLE | 否 | MANAGE_ROLE | 否 |
+| CREATE_ROLE | 否 | MANAGE_ROLE | 否 |
+| DELETE_ROLE | 否 | MANAGE_ROLE | 否 |
+| LIST_ROLE | 否 | -- IGNORE | |
+| GRANT_ROLE_PRIVILEGE | 否 | -- IGNORE | |
+| REVOKE_ROLE_PRIVILEGE | 否 | -- IGNORE | |
+| CREATE_FUNCTION | 否 | USE_UDF | 否 |
+| DROP_FUNCTION | 否 | USE_UDF | 否 |
+| CREATE_TRIGGER | 是 | USE_TRIGGER | 否 |
+| DROP_TRIGGER | 是 | USE_TRIGGER | 否 |
+| START_TRIGGER | 是 | USE_TRIGGER | 否 |
+| STOP_TRIGGER | 是 | USE_TRIGGER | 否 |
+| CREATE_CONTINUOUS_QUERY | 否 | USE_CQ | 否 |
+| DROP_CONTINUOUS_QUERY | 否 | USE_CQ | 否 |
+| ALL | 否 | All privilegs | |
+| DELETE_DATABASE | 是 | MANAGE_DATABASE | 否 |
+| ALTER_TIMESERIES | 是 | WRITE_SCHEMA | 是 |
+| UPDATE_TEMPLATE | 否 | -- IGNORE | |
+| READ_TEMPLATE | 否 | -- IGNORE | |
+| APPLY_TEMPLATE | 是 | WRITE_SCHEMA | 是 |
+| READ_TEMPLATE_APPLICATION | 否 | -- IGNORE | |
+| SHOW_CONTINUOUS_QUERIES | 否 | -- IGNORE | |
+| CREATE_PIPEPLUGIN | 否 | USE_PIPE | 否 |
+| DROP_PIPEPLUGINS | 否 | USE_PIPE | 否 |
+| SHOW_PIPEPLUGINS | 否 | -- IGNORE | |
+| CREATE_PIPE | 否 | USE_PIPE | 否 |
+| START_PIPE | 否 | USE_PIPE | 否 |
+| STOP_PIPE | 否 | USE_PIPE | 否 |
+| DROP_PIPE | 否 | USE_PIPE | 否 |
+| SHOW_PIPES | 否 | -- IGNORE | |
+| CREATE_VIEW | 是 | WRITE_SCHEMA | 是 |
+| ALTER_VIEW | 是 | WRITE_SCHEMA | 是 |
+| RENAME_VIEW | 是 | WRITE_SCHEMA | 是 |
+| DELETE_VIEW | 是 | WRITE_SCHEMA | 是 |
