The operations, administration, and management (OAM) tool lectl is a command-line tool provided by Link IoT Edge to manage resources. It allows you to use Link IoT Edge efficiently.
Help
lectl
command or a lectl subcommand to retrieve help information. The following code shows
the top-level help information:
$ lectl --help
Usage: lectl [OPTIONS] COMMAND
Manage Link IoT Edge services and facilitate troubleshooting.
Options:
-v, --version Print version information and quit
Commands:
completion Output shell completion code
config Manage configs
dbus Manage D-Bus message bus
deployment Manage deployments
device Manage devices
diagnose Check if requirements meet
driver Manage drivers
fc Manage function compute
logger Manage logger service and logs
mqtt Manage MQTT service
ota Manage OTA service
rom Manage remote operations and maintenance
router Manage message routing
sc Manage stream compute
scene Manage scenes
Run 'lectl COMMAND --help' for more information on a command.
Autocomplete
lectl supports the autocomplete feature of the bash and zsh shells to improve input efficiency.
- bash
Run the lectl completion bash command on the gateway to generate the bash autocomplete script. Then, import the script to the current shell.
The bash autocomplete script depends on the bash-completion package. Different package management systems provide different bash-completion packages. Perform the following steps to enable the autocomplete feature for lectl.
- Run the type _init_completion command on the gateway to check whether the bash-completion package has been installed.
- If the package has been installed, go to step 4.
- If the package has not been installed, go to step 2.
- Use the package management system to install the bash-completion package.
- If you are using Red Hat Linux operating systems, run the yum install bash-completion command.
- If you are using Debian Linux operating systems, run the apt-get install bash-completion command.
For more information about bash-completion packages that are provided by different package management systems, see bash-completion.
- Add the content of the generated /usr/share/bash-completion/bash_completion file to the .bashrc file.
source /usr/share/bash-completion/bash_completion
- Enable the autocomplete feature.
You can use either of the following methods:
- Import the bash autocomplete script to the current shell. (Recommended)
source <(lectl completion bash)
Note If you use this method, the autocomplete feature is invalid after you exit the shell. If you want the autocomplete feature to take effect all the time, run theecho 'source <(lectl completion bash)' >> ~/.bashrc
command to add the source <(lectl completion bash) command to the .bashrc file. - Add the bash autocomplete script to the bash_completion.d directory.
lectl completion bash > /etc/bash_completion.d/lectl
- Import the bash autocomplete script to the current shell. (Recommended)
- Run the type _init_completion command on the gateway to check whether the bash-completion package has been installed.
- zsh
Run the lectl completion zsh command to generate the zsh autocomplete script. Then, import the generated script to the current shell.
You can also run the following command on the gateway to generate the zsh autocomplete script and enable the autocomplete feature for lectl.source <(lectl completion zsh)
Note If thecomplete:13: command not found: compdef
error occurs, copy and paste the following command into the .zshrc file.autoload -Uz compinit compinit
Connection diagnosis
lectl diagnose
$ lectl diagnose
....................................................
Get Gateway Triple ***************************[ OK ]
Get IoT Region *******************************[ OK ]
Check Network ********************************[ OK ]
Check DNS Service ****************************[ OK ]
Check MQTT Port ******************************[ OK ]
Check MQTT Cert ******************************[ OK ]
Warning: Inspection of MQTT connection will offline edge-gateway(y or n)y
Gateway Produck Key : a17p****0p0
Gateway Device Name : TASN_******_LinkEdge_Core
Gateway Device Secret : 9ygH*************vZqfv
MQTT Service Host : a17p****0p0.iot-as-mqtt.cn-shanghai.aliyuncs.com
MQTT Service Port : 1883
Check MQTT Connection ************************[ OK ]
Field | Description |
---|---|
Get Gateway Triple | Queries the device certificate of the gateway. |
Get IoT Region | Queries the region of the IoT service. |
Check Network | Checks the network connection status. |
Check DNS Service | Checks the DNS service status. |
Check MQTT Port | Checks the port that the MQTT protocol uses. |
Check MQTT Cert | Checks the certificate for the MQTT client. |
Check MQTT Connection | Checks the MQTT connection. |
Manage logs
You can use the lectl tool to package logs or temporarily change Log Service behaviors. This allows you to upload logs or troubleshoot errors.
- Package logs
Run the following command to package logs:
lectl logger pack
Note By default, log files are packaged into the current directory and the package is named logs.zip. You can use the -n or --name option to specify the output file name, and the -o or --output option to specify the output path. - Manage Log Service
lectl allows you to retrieve Log Service configurations and temporarily change Log Service behaviors. For example, if errors occur on Link IoT Edge, you can change the global log level to debug to view more details.
Run the following command to retrieve Log Service configurations or temporarily change Log Service behaviors:lectl logger config [OPTIONS]
Note You can use the lectl logger config command to configure multiple logging options at a time.Table 2. Options Option Description -d, --disable Disables the logging system, log level, module logging, module log level, logging destination, or display format. You can disable only one feature at a time. -e, --enable Enables the logging system, log level, module logging, module log level, logging destination, or display format. You can enable only one feature at a time. --show Displays all or specified configurations. Syntax: --show=
.You can specify the following configuration items:
- dir: the log file path.
- level: the global log level.
- module: the module log configurations.
- format: the log display format.
- target: the logging destination.
- size: the log file size.
-g, --single-file-mb Sets the size of a single log file. Unit: MB. -t, --total-files-mb Sets the overall log file size. Unit: MB. The following examples show common commands that are used to manage Log Service:
$ lectl logger config --show $ lectl logger config --show=level $ lectl logger config -g 10 $ lectl logger config -t 1024 $ lectl logger config -e system $ lectl logger config -e warn $ lectl logger config -e credential $ lectl logger config -e credential:info $ lectl logger config -e stdout $ lectl logger config -e full $ lectl logger config -d warn
Manage Link IoT Edge configurations
You can use the config subcommand to manage Link IoT Edge configurations.
- Retrieve configurations
Run the following command to retrieve configurations:
lectl config get [OPTIONS] [ARG]
By default, the [ARG] parameter specifies the key of the value to be retrieved and changes based on the [OPTIONS] parameter. The following table lists the valid options.
Table 3. Options Option Description -d, --d3 Retrieves the certificate information of all devices. You do not need to specify the [ARG] parameter. -v, --driver Retrieves the configurations of a specified driver. [ARG] specifies the driver name. -g, --g3 Retrieves the certificate information of the gateway device. You do not need to specify the [ARG] parameter. -s, --tsl Retrieves the TSL of a specified product. [ARG] specifies the product key. The following examples show common commands that are used to retrieve configurations:$ lectl config get foo $ lectl config get -g $ lectl config get -d $ lectl config get -s foo $ lectl config get -v foo
- Configure devices
Run the following command to configure devices:
lectl config set [OPTIONS] [ARG...]
By default, the [ARG...] parameter includes the ARG1, ARG2, and ARG3 parameters that specify the key, value, and timestamp, respectively. The timestamp is optional. The [ARG...] parameter changes based on the [OPTIONS] parameter. The following table lists the valid options.
Table 4. Options Option Description -d, --d3 Configures the device certificate. The ARG1, ARG2, and ARG3 parameters specify the product key, device name, and device secret, respectively. -p, --d3f Reads a specified file to configure the device certificate. The ARG1 parameter specifies the file path. You do not need to specify the ARG2 and ARG3 parameters. -v, --driver Configures the driver. The ARG1 and ARG2 parameters specify the driver name and driver configurations, respectively. You do not need to specify the ARG3 parameter. -f, --file Reads a specified file to configure key-value pairs. The ARG1 and ARG2 parameters specify the key and file path, respectively. You do not need to specify the ARG3 parameter. -g, --g3 Configures the device certificate of the gateway. The ARG1, ARG2, and ARG3 parameters specify the product key, device name, and device secret, respectively. -s, --tsl Configures the TSL of the product. The ARG1 and ARG2 parameters specify the product key and file path, respectively. The following examples show common commands that are used to configure devices:$ lectl config set foo bar $ lectl config set foo bar 1555483052 $ lectl config set -f foo /path/to/bar $ lectl config set -g foo bar baz $ lectl config set -d foo bar baz $ lectl config set -p /path/to/foo $ lectl config set -s foo /path/to/bar $ lectl config set -v foo bar
- Remove configurations
Run the following command to remove configurations:
lectl config unset KEY
- Force to write configurations
To ensure successful configuration, you can force the system to write configurations and save the configurations to a disk. Run the following command:
lectl config flush
Management D-Bus
Internal components of Link IoT Edge use the D-Bus message bus to communicate with each other. You can use the dbus subcommand to manage Link IoT Edge D-Bus.
Run the following command to monitor messages in D-Bus:
lectl dbus monitor
Manage deployment
You can use the deployment subcommand to manage the deployment of edge instances.
You can use the lectl deployment show command to view the deployment information of edge instances.
Manage drivers
You can use the driver subcommand to manage Link IoT Edge drivers.
Run the following command to view driver details:
lectl driver show [OPTIONS] DRIVER
Parameter | Description |
---|---|
[OPTIONS] | For information about this parameter, see the following table. |
DRIVER | The ID of the driver. |
Option | Description |
---|---|
-c, --connections | If you specify this option, only the driver connection information is displayed. If you do not specify this option, all driver information is displayed. |
--devices | If you specify this option, only the device information is displayed. If you do not specify this option, all driver information is displayed. You can specify the product key and device name to filter devices. |
The following examples show common commands that are used to manage drivers:
$ lectl driver show 44c0****78204641a4b9bcf1024176c2
$ lectl driver show -c 44c0****78204641a4b9bcf1024176c2
$ lectl driver show --devices 44c0****78204641a4b9bcf1024176c2
$ lectl driver show --devices=a1t8****n42K/GjCb****gcKYaluGJLN 44c0****78204641a4b9bcf1024176c2
Manage devices
You can use the device subcommand to manage Link IoT Edge devices.
- View device information
Run the lectl device show subcommand to view the status of the current device.
The following example shows the device information:lectl device show { "DeviceStats": [ { "ProductKey": "a1t9****42K", "DeviceName": "GjCb****gcKXeluGJLNp", "LocalId": "GjCb9****cKXeluGJLNp", "IsLocal": false, "DriverId": "e0bb****964e4519b4a52f9b719e1dd3", "Activation": "activated", "LocalState": "online", "CloudState": "online", "LastSeenTime": "2020-02-27T14:16:52+08:00", "LastRequestOnlineTime": "2020-02-27T14:16:52+08:00", "LastLocalOnlineTime": "2020-02-27T14:16:52+08:00", "LastCloudOnlineTime": "2020-02-27T14:16:52+08:00", "LastCloudOnlineFinishTime": "2020-02-27T14:16:52+08:00", "LastRequestOfflineTime": "2020-02-26T12:04:45+08:00", "LastLocalOfflineTime": "2020-02-26T12:04:45+08:00", "LastCloudOfflineTime": "2020-02-26T12:04:45+08:00", "LastCloudOfflineFinishTime": "2020-02-26T12:04:45+08:00", "RequestOnlineTimes": 17, "LocalOnlineTimes": 17, "CloudOnlineTimes": 252, "RequestOfflineTimes": 1, "LocalOfflineTimes": 1, "CloudOfflineTimes": 1 } ] }
Table 7. Fields Field Description ProductKey The unique identifier of the product. DeviceName The name of the device. DriverId The ID of the driver to which the device is associated. Activation Indicates whether the device is activated. LocalState The connection status between the device and the gateway. CloudState The connection status between the device and IoT Platform. - Retrieve device properties
You can use the getproperties subcommand to retrieve the property values of a specified device.
lectl device getproperties [OPTIONS]
Table 8. Options Option Required Description -i, --identifier Yes Identifies the device to be queried. Syntax: ProductKey/DeviceName
.--key Yes Identifies the keys of the properties. You must specify a JSON string array. The following example shows a common command that is used to retrieve device properties:
lectl device getproperties --identifier=a1t8****42K/GjCb****gcKYaluGJLNp --keys='["foo"]'
- Configure device properties
You can use the setproperties subcommand to configure the property values of a specified device.
lectl device setproperties [OPTIONS]
Table 9. Options Option Required Description -i, --identifier Yes Identifies the device to be queried. Syntax: ProductKey/DeviceName
.--properties Yes Identifies the keys of the properties. You must specify a JSON string array. The following example shows a common command that is used to configure device properties:
$ lectl device setproperties --identifier=a1t8****42K/GjCb****gcKYaluGJLNp --properties='["foo": "bar"]'
- Call device services
You can use the callservices subcommand to call the services of a specified device.
lectl device callservice [OPTIONS]
Table 10. Options Option Required Description -i, --identifier Yes Identifies the device to be queried. Syntax: ProductKey/DeviceName
.--name Yes Identifies the name of the service to be called. --args No Identifies the input parameters of the service to be called. The data format of parameters is defined by the service. The following examples show common commands that are used to call device services:
$ lectl device callservice --identifier=a1t8****42K/GjCb****gcKYaluGJLNp --name=foo $ lectl device callservice --identifier=a1t8****42K/GjCb****gcKYaluGJLNp --name=foo --args=bar $ lectl device callservice --identifier=a1t8****42K/GjCb****gcKYaluGJLNp --name=foo --args='["bar"]'
Manage scene orchestrations
You can use lectl to manage scene orchestrations in Link IoT Edge. lectl allows you to view, enable, disable, and trigger scene orchestrations.
- View scene orchestrations
Run the lectl scene show command to view the basic information, execution information, statistics, and deployment information of scene orchestrations.
The following example shows the result of running this command:
lectl scene show { "Scenes": [ { "Times": 8, "FailureTimes": 0, "LastState": { "State": "success", "Cause": "", "Time": "2020-02-27T14:25:00+08:00", "Duration": 3 }, "Id": "d141****2aaf4d1d8e3259637e489528", "Name": "scene_test_types", "Running": true, "Time": "2020-02-27T14:17:53+08:00", "Uptime": 466184, "Actions": { "Times": 8, "FailureTimes": 0, "LastState": { "State": "success", "Cause": "", "Time": "2020-02-27T14:25:00+08:00", "Duration": 2 } }, "Conditions": { "Times": 8, "FailureTimes": 0, "LastState": { "State": "success", "Cause": "", "Time": "2020-02-27T14:25:00+08:00", "Duration": 0 } } } ], "Deployment": null }
- Enable scene orchestrations
Run the following command to enable one or more scene orchestrations:
lectl scene enable SCENE [SCENE...]
The SCENE parameter specifies the IDs of the scene orchestrations. Multiple IDs must be separated with spaces.
- Disable scene orchestrations
Run the following command to disable one or more scene orchestrations:
lectl scene disable SCENE [SCENE...]
The SCENE parameter specifies the IDs of the scene orchestrations. Multiple IDs must be separated with spaces.
- Trigger scene orchestrations
Run the following command to trigger one or more scene orchestrations:
lectl scene invoke SCENE [SCENE...]
The SCENE parameter specifies the IDs of the scene orchestrations. Multiple IDs must be separated with spaces.
- Reset scene orchestrations
Run the following command to remove all scene orchestrations on the current gateway:
lectl scene reset
Manage functions
You can use lectl to manage functions in Link IoT Edge. lectl allows you to view, deploy, remove, reset, call, and restart functions.
- View function information
If exceptions occur during function execution, you can run the lectl fc show command to view the statuses and statistics of functions.
The following example shows the result of running this command:
$ lectl fc show { "Functions": [ { "FunctionId": "90fe****d2a5466993117e58c1ae3f7f", "ServiceName": "helloworld", "FunctionName": "helloworld", "Runtime": "nodejs8", "MemorySize": 1073741824, "Timeout": 5, "RunMode": "OnDemand", "Status": "Running", "InvocationTimes": 157, "ProcessStats": { "Pid": 254, "MemoryUsage": 32988, "StartTime": "2020-02-27 14:17:14.412906 ", "LastStopTime": "1970-01-01 08:00:00.000000 ", "LastInvokeTime": "2020-02-27 14:22:26.547315 ", "ExitTimes": 0 }, "TaskStats": { "HandledTimes": 157, "HandledErrorTimes": 0, "UnhandledTimes": 0, "HandledAverageDuration": 3025, "WaitingAverageDuration": 0, "LastHandledDuration": 2006 }, "RuntimeStats": { "RequestUnhandledTimes": 0, "RequestHandledTimes": 0, "RequestHandledErrorTimes": 0, "RequestHandledAverageDuration": 0 }, "DeploymentStats": { "State": "Success" } } ] }
- Call a function
Run the following command to call a function:
lectl fc invoke [OPTIONS] FUNCTION
Table 11. Parameters Parameter Description [OPTIONS] The options. The following options are available: -p, --payload: specifies the base64-encoded parameter value. The parameter value is left intact before being passed to the function.
FUNCTION The ID or Alibaba Resource Name (ARN) of the function. The syntax of a function ARN: acs:fc:<Region>:<AccountId>:service:<ServiceName>:function:<FunctionName>
. - Restart functions
Run the following command to restart one or more functions:
lectl fc restart FUNCTION [FUNCTION...]
The FUNCTION parameter specifies the IDs of the functions. Multiple function IDs must be separated with spaces.
- Remove functions
Run the following command to remove one or more functions:
lectl fc remove FUNCTION [FUNCTION...]
The FUNCTION parameter specifies the IDs of the functions. Multiple function IDs must be separated with spaces.
- Reset deployment
Run the following command to reset the deployment:
lectl fc reset
Manage remote services
You can use the rom subcommand to manage remote services in Link IoT Edge.
Run the following command to view the statuses of the current remote services:
lectl rom show
Field | Description |
---|---|
ChannelState | The status of the channel connection. |
ThreadState | The status of the thread. |
Services | The list of remote services and their statuses. |
Manage MQTT messaging
You can use the mqtt subcommand to manage MQTT-based message subscriptions of Link IoT Edge components.
Run the following command to view the message subscriptions of Link IoT Edge components:
lectl mqtt show
Field | Description |
---|---|
Topic | The topic whose messages are subscribed. |
QoS | The Quality of Service (QoS) level that is defined in the MQTT protocol. |
Subscriber | The subscriber of the message. |
State | The status of the message subscription. |
Time | The time when the message was subscribed. |