Meta service commands¶
This page covers ngctl commands for signing in to the Meta service, changing passwords, managing users, and checking the client version.
When you run the user management commands, replace <username> in the command syntax with the actual username.
Log in to Meta ¶
Logs in to a Meta service.
Command syntax¶
ngctl auth login --host <host> --port <port> --user <username> --password <password> --enable-tls true|false --tls-skip-verify true|false --tls-ca <ca_file_path> --tls-cert <cert_file_path> --tls-key <key_file_path> --tokenFile <token_file_path>
Options¶
| Option | Alias | Description | Required | Type |
|---|---|---|---|---|
--host |
-H |
The host address of the Meta service. Developer Edition has one Meta service. Default value: "127.0.0.1". |
No | String |
--port |
-P |
The port number of the Meta service. Default value: 9559. |
No | Integer |
--user |
-u |
The name of the user to log in. Default value: root. |
No | String |
--password |
-p |
The password of the user. The password must be at least 8 characters long and contain at least one uppercase letter, one lowercase letter, and one digit. If a password contains shell special characters such as $, wrap it in quotes according to your shell. |
Yes | String |
--force |
-f |
Force the login operation even if the Meta service is not the leader. If true, bypass the leader check to log in to the specified Meta service. Default: false. |
No | Bool |
--enable-tls |
- | Whether to enable TLS. Valid values: true and false. Default value: false. |
No | Bool |
--tls-skip-verify |
- | Whether to disable server certificate verification. Valid values: true and false. Default value: false |
No | Bool |
--tls-ca |
- | The path to the CA (Certificate Authority) certificate file, which is used to verify the server's certificate. Required if --enable-tls is set to true and --tls-skip-verify is set to false. |
No | String |
--tls-cert |
- | The path to the certificate file of the client. Required if tls_client_verify is set to true in the configuration file of NebulaGraph Database Developer Edition's Meta service. |
No | String |
--tls-key |
- | The path to the private key file of the client. Required if tls_client_verify is set to true in the configuration file of NebulaGraph Database Developer Edition's Meta service. |
No | String |
--tokenFile |
- | The path to the file where the Meta access token is stored. If not set, the path $HOME/.nebula_meta_token is used by default. If a custom path is specified when you run this command, this option must be set to the custom path in all subsequent commands until after you log out of Meta. |
No | String |
Log out of Meta ¶
Logs out of a Meta service.
Command syntax¶
ngctl auth logout --tokenFile <token_file_path>
Options¶
| Option | Alias | Description | Required | Type |
|---|---|---|---|---|
--tokenFile |
- | The path to the file where the Meta access token is stored. If not set, the path $HOME/.nebula_meta_token is used by default. If a custom path is specified when you log in to Meta, this option must be set to the custom path. |
No | String |
Change a password ¶
Use ngctl auth passwd to change your own password by providing your username, current password, and new password. You do not need to sign in to the Meta service first. If you have forgotten your current password, ask an administrator to reset it.
Command syntax¶
ngctl auth passwd --host <host> --port <port> --user <username> --current_password <current_password> --new_password <new_password> --enable-tls true|false --tls-skip-verify true|false --tls-ca <ca_file_path> --tls-cert <cert_file_path> --tls-key <key_file_path> --tokenFile <token_file_path>
Options¶
| Option | Alias | Description | Required | Type |
|---|---|---|---|---|
--host |
-H |
The host address of the Meta service. Default value: "127.0.0.1". |
No | String |
--port |
-P |
The port number of the Meta service. Default value: 9559. |
No | Integer |
--user |
-u |
Your username. You must provide this user's current password. Default value: root. |
No | String |
--current_password |
-c |
The specified user's current password, used to verify identity. | Yes | String |
--new_password |
-p |
The new password of the user. The password must be at least 8 characters long and contain at least one uppercase letter, one lowercase letter, and one digit. | Yes | String |
--enable-tls |
- | Whether to enable TLS. Valid values: true and false. Default value: false. |
No | Bool |
--tls-skip-verify |
- | Whether to disable server certificate verification. Valid values: true and false. Default value: false |
No | Bool |
--tls-ca |
- | The path to the CA (Certificate Authority) certificate file, which is used to verify the server's certificate. Required if --enable-tls is set to true and --tls-skip-verify is set to false. |
No | String |
--tls-cert |
- | The path to the certificate file of the client. Required if tls_client_verify is set to true in the configuration file of NebulaGraph Database Developer Edition's Meta service. |
No | String |
--tls-key |
- | The path to the private key file of the client. Required if tls_client_verify is set to true in the configuration file of NebulaGraph Database Developer Edition's Meta service. |
No | String |
--tokenFile |
- | Path to an existing Meta token file, used to read saved connection settings. Defaults to $HOME/.nebula_meta_token. This command does not use a login token to verify identity. |
No | String |
Create user ¶
Creates a user in the Meta service. The username <username> must be 4 to 32 characters in length and include only letters, digits, and underscores.
Command syntax¶
ngctl user create <username> --password <password> --encrypt-type <encrypt_type> --tokenFile <token_file_path>
or
ngctl user create <username> --auth-type <auth_type> --auth-info <auth_info> --encrypt-type <encrypt_type> --tokenFile <token_file_path>
Options¶
| Option | Alias | Description | Required | Type |
|---|---|---|---|---|
--password |
-p |
The password must be at least 8 characters in length and include at least one digit, one lowercase letter, and one uppercase letter. Required if --auth-type is not specified. |
No | String |
--encrypt-type |
-e |
The encryption type of the user password. Valid value: sha256 (default), sha512, and sm3. |
No | String |
--auth-type |
- | The authentication type of the user. Valid value: password. Required if --password is not specified. |
No | String |
--auth-info |
- | The authentication information of the user in a JSON string. For the authentication type password, the authentication information must be in the format of '{"password":"<password>"}'. Required if --password is not specified. |
No | String |
--tokenFile |
- | The path to the file where the Meta access token is stored. If not set, the path $HOME/.nebula_meta_token is used by default. If a custom path is specified when you log in to Meta, this option must be set to the custom path. |
No | String |
Drop user ¶
Deletes a user from the Meta service.
Command syntax¶
ngctl user drop <username> --tokenFile <token_file_path>
Options¶
| Option | Alias | Description | Required | Type |
|---|---|---|---|---|
--tokenFile |
- | The path to the file where the Meta access token is stored. If not set, the path $HOME/.nebula_meta_token is used by default. If a custom path is specified when you log in to Meta, this option must be set to the custom path. |
No | String |
Reset a user's password as an administrator ¶
First sign in to the Meta service as root, then use ngctl user alter to set a new password for the target user. You do not need that user's old password. If the target user is disabled, enable the user before resetting the password.
Command syntax¶
ngctl user alter <username> --password <password> --encrypt-type <encrypt_type> --tokenFile <token_file_path>
or
ngctl user alter <username> --auth-info <auth_info> --encrypt-type <encrypt_type> --tokenFile <token_file_path>
Options¶
| Option | Alias | Description | Required | Type |
|---|---|---|---|---|
--password |
-p |
The target user's new password; the old password is not required. The password must be at least 8 characters in length and include at least one digit, one lowercase letter, and one uppercase letter. Required if --auth-info is not specified. |
No | String |
--encrypt-type |
-e |
The encryption type of the user password. Valid value: sha256 (default), sha512, and sm3. |
No | String |
--auth-info |
- | The new authentication information of the user in a JSON string. For the authentication type password, the authentication information must be in the format of '{"password":"<password>"}'. Required if --password is not specified. |
No | String |
--tokenFile |
- | The path to the file where the Meta access token is stored. If not set, the path $HOME/.nebula_meta_token is used by default. If a custom path is specified when you log in to Meta, this option must be set to the custom path. |
No | String |
Enable user ¶
Enables a user in the Meta service.
Command syntax¶
ngctl user enable <username> --tokenFile <token_file_path>
Options¶
| Option | Alias | Description | Required | Type |
|---|---|---|---|---|
--tokenFile |
- | The path to the file where the Meta access token is stored. If not set, the path $HOME/.nebula_meta_token is used by default. If a custom path is specified when you log in to Meta, this option must be set to the custom path. |
No | String |
Disable user ¶
Disables a user in the Meta service.
Command syntax¶
ngctl user disable <username> --tokenFile <token_file_path>
Options¶
| Option | Alias | Description | Required | Type |
|---|---|---|---|---|
--tokenFile |
- | The path to the file where the Meta access token is stored. If not set, the path $HOME/.nebula_meta_token is used by default. If a custom path is specified when you log in to Meta, this option must be set to the custom path. |
No | String |
Unlock user ¶
Unlocks a user who is temporarily locked because of too many failed login attempts.
unlock clears a user's temporary lock status and does not change whether the user is active. If the user has been disabled, you still need to enable the user before the user can connect to service groups.
Command syntax¶
ngctl user unlock <username> --tokenFile <token_file_path>
Options¶
| Option | Alias | Description | Required | Type |
|---|---|---|---|---|
--tokenFile |
- | The path to the file where the Meta access token is stored. If not set, the path $HOME/.nebula_meta_token is used by default. If a custom path is specified when you log in to Meta, this option must be set to the custom path. |
No | String |
Show users ¶
Displays details about one or more users in the Meta service.
Command syntax¶
ngctl user show <username> --output <output_format> --tokenFile <token_file_path>
Options¶
| Option | Alias | Description | Required | Type |
|---|---|---|---|---|
--output |
-o |
The output format. Valid values: table and json. Default value: table. |
No | String |
--tokenFile |
- | The path to the file where the Meta access token is stored. If not set, the path $HOME/.nebula_meta_token is used by default. If a custom path is specified when you log in to Meta, this option must be set to the custom path. |
No | String |
Response parameters¶
| Parameter | Description |
|---|---|
Name |
The name of the user. |
Active |
Whether the user is active. |
Auth Type |
The authentication type of the user. |
Auth Info |
The authentication information of the user. |
Created Time |
The time when the user was created. |
Last Updated Time |
The last time when the user was altered. |
Disabled Time |
The time when the user was disabled. |
Examples¶
./ngctl user show
Name Active Auth Type Auth Info Created Time Last Updated Time Disabled Time
root Y password 2025-04-30T08:30:23Z 2025-04-30T08:30:23Z
View ngctl version¶
Displays the version of ngctl.
Command syntax¶
ngctl version
Examples¶
./ngctl version
Version:
Git commit: 9109557
Build time: 2024-10-28T18:33:08+0000