管理运维工具lectl

lectl管理运维工具(以下统称lectl)是物联网边缘计算提供的管理Link IoT Edge及其资源的命令行工具,可帮助您更好的使用Link IoT Edge。

您可以在{LINKEDGE_ROOT}/gateway/build/bin目录下找到lectl工具。
说明 {LINKEDGE_ROOT}指Link IoT Edge软件包根目录所在的路径,通常为/linkedge/

获取帮助

lectl及子命令后添加--help命令,可获取帮助信息。顶层的帮助信息如下所示。
$ 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
  console     Manage console backend
  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 log service and logs
  mqtt        Manage MQTT service
  ota         Manage OTA service
  rom         Manage remote maintenance
  router      Manage message routing
  sc          Manage stream compute
  scene       Manage scenes

Run 'lectl COMMAND --help' for more information on a command.

自动补全

lectl支持bash和zsh的自动补全功能,提升输入效率。

  • bash

    通过在网关上执行lectl completion bash命令,生成lectl的bash自动补全脚本,并将脚本导入到Shell中,即可启动lectl的bash自动补全功能。

    但由于bash自动补全脚本依赖bash-completion,且各种包管理系统提供的bash-completion不同,因此您需要按照如下步骤启动lectl的bash自动补全功能。

    1. 在网关上执行type _init_completion命令,检查系统是否安装了bash自动补全脚本依赖的bash-completion。
      • 已安装:请跳转到步骤iv。
      • 未安装:请跳转到步骤ii。
    2. 通过系统自带的包管理系统,安装bash-completion。
      • RedHat系列操作系统:yum install bash-completion
      • Debian系列操作系统:apt-get install bash-completion

      关于更多包管理系统提供的bash-completion相关信息,请参见开源库

    3. 将安装bash-completion后生成的/usr/share/bash-completion/bash_completion文件添加到.bashrc文件中。
      source /usr/share/bash-completion/bash_completion
    4. 启用自动补全功能。
      有如下两种启用方法:
      • 直接导入bash自动补全脚本到当前的Shell。(推荐使用)
        source <(lectl completion bash)
        说明 使用此方法后,在退出Shell时自动补全功能失效。若需要自动补全功能一直生效,请执行echo 'source <(lectl completion bash)' >> ~/.bashrc,将此命令添加到.bashrc文件中。
      • 将bash自动补全脚本添加到bash_completion.d目录。
        lectl completion bash > /etc/bash_completion.d/lectl
  • zsh

    通过lectl completion zsh命令,生成lectl的zsh自动补全脚本,并将生成的脚本导入到Shell中,即可启用zsh自动补全功能。

    在网关上执行如下命令,一步实现生成zsh自动补全脚本和启用自动补全功能。
    source <(lectl completion zsh)
    说明 如果出现complete:13: command not found: compdef错误,请将如下命令复制粘贴到.zshrc文件里。
    autoload -Uz compinit
    compinit

连接诊断

当Link IoT Edge网关无法连接到云端时,您可以通过lectl工具,使用diagnose命令做初步诊断。
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 ]
表 1. 字段说明
字段描述
Get Gateway Triple获取网关设备的设备证书。
Get IoT Region获取地域配置。
Check Network检查网络连接状态。
Check DNS Service检查DNS服务状态。
Check MQTT Port检查MQTT协议端口。
Check MQTT Cert检查MQTT协议证书。
Check MQTT Connection检查MQTT连接。

管理日志

您可以使用lectl工具,打包日志或临时改变日志服务行为,方便在出问题时上传日志或临时排查。

  • 打包日志
    执行如下命令打包日志。
    lectl logger pack
    说明 日志文件被默认打包到当前目录并命名为logs.zip。您也可以通过-n--name选项指定输出文件名,-o--output选项指定输出路径。
  • 管理日志服务

    lectl允许获取日志服务配置,并临时改变日志服务行为。例如,Link IoT Edge出现问题时可以调整全局日志等级到debug,以显示更多详细信息。

    获取日志服务配置和改变日志服务行为主要通过如下命令实现。
    lectl logger config [OPTIONS]
    说明 lectl logger config命令支持一次配置多个日志选项。
    表 2. [OPTIONS] 选项说明
    选项名称描述
    -d,--disable关闭日志系统、日志等级、模块日志、模块日志等级、输出目标、显示格式等。不能一次关闭多项内容。
    -e,--enable开启日志系统、日志等级、模块日志、模块日志等级、输出目标、显示格式等。不能一次开启多项内容。
    --show显示所有配置或指定配置信息。此选项只能以--show=形式指定。

    指定配置项包括:

    • dir:日志文件路径
    • level:全局日志等级
    • module:模块日志配置
    • format:日志显示格式
    • target:日志输出目标
    • size:日志文件大小
    -g,--single-file-mb设置单个日志文件大小(单位为MB)。
    -t,--total-files-mb设置总体日志文件大小(单位为MB)。

    常见的lectl logger config命令示例如下。

    $ 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

管理配置

配置管理主要通过config子命令实现。

  • 获取配置
    使用如下命令获取配置。
    lectl config get [OPTIONS] KEY

    [OPTIONS]用于提供常见复杂用法的快捷方式,通常拥有独立的参数。

    表 3. [OPTIONS] 选项说明
    选项名称描述
    -d,--d3获取所有设备的设备证书信息,无独立参数。
    -v,--driver获取给定驱动的配置,要求1个参数,表示驱动名。
    -g,--g3获取网关设备的设备证书信息,无独立参数。
    -s,--tsl获取给定产品的TSL(物模型),要求1个参数,表示产品的ProductKey。
    常见的获取配置命令示例如下。
    $ lectl config get foo
    $ lectl config get -g
    $ lectl config get -d
    $ lectl config get -s foo
    $ lectl config get -v foo
  • 设置配置
    使用如下命令设置设备配置。
    lectl config set [OPTIONS] KEY VALUE

    [OPTIONS]用于提供常见复杂用法的快捷方式,通常拥有独立的参数。

    表 4. [OPTIONS] 选项说明
    选项名称描述
    -d,--d3设置设备证书信息,要求3个参数,分别表示ProductKey、DeviceName和DeviceSecret。
    -p,--d3f从给定的文件读取并设置设备证书信息,要求1个参数,表示文件路径。
    -v,--driver设置驱动配置,要求2个参数,分别表示驱动名和驱动配置。
    -f,--file从给定的文件读取并设置键、值,要求2个参数,分别表示键和文件路径。
    -g,--g3设置网关的设备证书信息,要求3个参数,分别表示ProductKey、DeviceName和DeviceSecret。
    -s,--tsl设置产品的TSL,要求2个参数,分别表示产品的ProductKey和TSL文件路径。
    常见的设备配置命令示例如下。
    $ lectl config set foo bar
    $ 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 /path/to/bar
  • 移除配置
    使用如下命令移除配置。
    lectl config unset KEY
  • 强制写入
    为确保配置操作执行成功,您可以强制配置,并保存数据到磁盘。命令如下。
    lectl config flush

管理D-BUS

Link IoT Edge内部组件使用D-Bus通信,可以通过dbus子命令来管理Link IoT Edge内D-Bus消息总线。

通过如下命令可以监听D-Bus总线上的消息。

lectl dbus monitor

管理部署

您可以通过deployment子命令,管理边缘实例的部署服务。

可通过lectl deployment show命令,显示边缘实例的部署信息。

管理驱动

您可以通过driver子命令,管理Link IoT Edge的驱动。

通过如下命令,查看驱动详细信息。

说明 此命令的返回信息依赖被操作的驱动,如果驱动没有对外显示接口,则无法显示相关信息。
lectl driver show [OPTIONS] DRIVER
表 5. 参数说明
选项名称描述
[OPTIONS]详细说明请参见本表格下方“[OPTIONS]选项说明”表。
DRIVER被操作驱动的ID。
表 6. [OPTIONS] 选项说明
选项名称描述
-c, --connections只显示驱动连接信息。默认显示驱动所有信息。
--devices只显示设备信息。默认显示驱动所有信息。您可以指定设备的ProductKey和DeviceName过滤设备。

常见的管理驱动命令示例如下。

$ 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

管理设备

您可以通过device子命令来管理Link IoT Edge的设备相关信息。

  • 显示信息

    当前设备的状态信息,可通过lectl device show子命令查看。

    一个显示信息片段如下。
    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
            }      
        ]
    }
    表 7. 字段说明
    选项名称描述
    ProductKey产品唯一标识。
    DeviceName设备名称。
    DriverId关联该设备的驱动ID。
    Activation设备状态是否为已激活。
    LocalState设备与网关的连接状态。
    CloudState设备与云端的连接状态。
  • 获取设备属性

    可通过getproperties子命令,获取指定设备的属性值。

    lectl device getproperties [OPTIONS]
    表 8. [OPTIONS] 选项说明
    选项名称是否必选描述
    -i, --identifier用于标识要获取属性的设备。格式为ProductKey/DeviceName
    --key用于标识要获取的属性的键。格式为JSON字符串数组。

    常用的获取设备属性命令示例如下。

    lectl device getproperties --identifier=a1t8****42K/GjCb****gcKYaluGJLNp --keys='["foo"]'
  • 设置设备属性

    可通过setproperties子命令,设置指定设备的属性值。

    lectl device setproperties [OPTIONS]
    表 9. [OPTIONS] 选项说明
    选项名称是否必选描述
    -i, --identifier用于标识要设置属性的设备。格式为ProductKey/DeviceName
    --properties用于标识要设置的属性的键。格式为JSON字符串对象。

    常用的设置设备属性命令示例如下。

    $ lectl device setproperties --identifier=a1t8****42K/GjCb****gcKYaluGJLNp --properties='["foo": "bar"]'
  • 调用设备服务

    可通过callservices子命令,调用指定设备上的服务。

    lectl device callservice [OPTIONS]
    表 10. [OPTIONS] 选项说明
    选项名称是否必选描述
    -i, --identifier用于标识被调服务所在的设备。格式为ProductKey/DeviceName
    --name用于标识被调服务的名称。
    --args用于标识被调服务的传入参数,格式由被调服务定义。

    常用的调用设备服务命令示例如下。

    $ 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"]'

管理控制台

您可以通过console子命令来管理Link IoT Edge提供的边缘网关控制台,包括设置证书和设置登录密码等。

  • 设置证书

    您可以通过如下命令设置边缘网关控制台证书:

    lectl console certificate <SUBJECT>

    其中,<SUBJECT>格式为/type0=value0/type1=value1...

    说明 type取值有C(Country)、ST(State)、L(Localcity)、O(Organization)、OU(Organization Unit)、CN(Common Name)。更多信息,请参见OpenSSL文档

    默认证书的<SUBJECT>/C=CN/ST=Zhejiang/L=Hangzhou/O=Link IoT Edge/OU=Link IoT Edge/CN=Link IoT Edge

  • 设置密码

    您可以通过如下命令设置或更新边缘网关控制台用户密码:

    lectl console password [OPTIONS]
    表 11. [OPTIONS] 选项说明
    选项名称是否必选描述
    -u, --username要更新密码的用户名。
    -p, --password新的密码。

管理场景联动

您可以通过lectl来管理Link IoT Edge上运行的场景联动,包括场景信息的显示、启用、停用、触发场景联动等。

  • 显示信息

    您可以通过lectl scene show命令查看场景的基本信息、执行信息、统计信息、部署信息等。

    执行命令后的结果示例如下。

    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
    }
  • 启动场景联动

    执行如下命令,启动一个或多个场景联动。

    lectl scene enable SCENE [SCENE...]

    其中,SCENE为场景联动的ID,多个场景联动ID之间以空格间隔。

  • 停止场景联动

    执行如下命令,停止一个或多个场景联动。

    lectl scene disable SCENE [SCENE...]

    其中,SCENE为场景联动的ID,多个场景联动ID之间以空格间隔。

  • 触发场景联动

    执行如下命令,触发一个或多个场景联动。

    lectl scene invoke SCENE [SCENE...]

    其中,SCENE为场景联动的ID,多个场景联动ID之间以空格间隔。

  • 重置场景联动

    执行如下命令,移除当前网关上的所有场景联动。

    lectl scene reset

管理函数计算

可以通过lectl管理Link IoT Edge上的函数计算。包括显示信息、部署函数、移除函数、重置部署、调用函数、重启函数等。

  • 显示信息

    当函数运行异常时,可通过lectl fc show命令查看函数的运行状态及统计信息。

    执行命令后的结果如下。

    $ 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"
                }
            }
        ]
    }
  • 调用函数

    使用如下命令调用一个函数。

    lectl fc invoke [OPTIONS] FUNCTION
    表 12. 参数说明
    选项名称描述
    [OPTIONS]OPTIONS选项,包含如下选项。

    -p, --payload:Base64编码后的参数内容。该参数内容将被原封不动的传给函数。

    FUNCTION函数ID或者函数ARN(资源名称,Aliyun Resource Name)。函数ARN格式为acs:fc:<Region>:<AccountId>:service:<ServiceName>:function:<FunctionName>
  • 重启函数
    使用如下命令重启一个或多个函数。
    lectl fc restart FUNCTION [FUNCTION...]

    其中,FUNCTION为函数ID,多个函数ID以空格间隔。

  • 移除函数
    使用如下命令移除一个或多个函数。
    lectl fc remove FUNCTION [FUNCTION...]

    其中,FUNCTION为函数ID,多个函数ID以空格间隔。

  • 重置部署
    使用如下命令重置部署。
    lectl fc reset

管理流数据分析

您可以在Link IoT Edge专业版(LE Pro)中使用lectl工具管理流数据分析。

  • 显示信息
    可通过lectl sc show命令查看当前系统流数据任务状态。代码片段
    表 13. 字段说明
    选项名称描述
    ID流数据任务ID。
    Name流数据任务名称。
    Running流数据任务是否正在运行。
    SQLPathSQL语句文件路径。
    SQLMd5SQL语句文件MD5值。
    LogPath流数据任务日志路径。
    BlinkJobId流数据任务在Blink中对应的任务ID。
  • 启动流数据任务
    使用如下命令启动一个或多个流数据任务。
    lectl sc start STREAM [STREAM...]

    其中,STREAM为流数据任务ID,多个流数据任务ID以空格间隔。

  • 停止流数据任务
    使用如下命令停止一个或多个流数据任务。
    lectl sc stop STREAM [STREAM...]

    其中,STREAM为流数据任务ID,多个流数据任务ID以空格间隔。

  • 验证SQL
    将SQL语句保存到指定文件,并执行如下命令验证流数据任务的SQL语句是否正确。
    lectl sc checksql FILE

管理远程服务

您可以通过rom子命令,管理Link IoT Edge的远程服务相关信息。

执行如下命令,可以显示远程服务当前状态。

lectl rom show
表 14. 字段说明
选项名称描述
ChannelState远程服务的通道连接状态。
ThreadState远程服务线程状态。
Services远程服务列表及其状态。

管理MQTT

您可以通过mqtt子命令,管理Link IoT Edge组件的MQTT消息订阅。

执行如下命令,可以显示Link IoT Edge组件的消息订阅。

lectl mqtt show
表 15. 字段说明
选项名称描述
Topic消息订阅的主题。
QoS服务质量,对应MQTT协议QoS。
Subscriber消息的订阅者。
State消息的订阅状态。
Time消息的订阅时间。