日志服务 LogListener 安装指南（Linux 版）

LogListener 是腾讯云日志服务（Cloud Log Service，CLS）所提供的专用日志采集器，将它安装部署到服务器上，可快速采集日志到日志服务。
安装环境
本文将介绍 Linux 操作系统环境下 LogListener 的安装，Windows 操作系统请参见 LogListener 安装指南（Windows 版）。
说明：
如果其他版本环境安装异常，请 提交工单 联系我们。
处理器架构
操作系统类别
确定可安装环境
x64/ARM
TencentOS Server
TencentOS Server 3.1、TencentOS Server 2.4
﻿
CentOS（64位）
CentOS_6.8_64位、CentOS_6.9_64位、CentOS_7.2_64位、CentOS_7.3_64位、CentOS_7.4_64位、CentOS_7.5_64位、CentOS_7.6_64位、CentOS_8.0_64位
﻿
Ubuntu（64位）
Ubuntu Server_14.04.1_LTS_64位、Ubuntu Server_16.04.1_LTS_64位、Ubuntu Server_18.04.1_LTS_64位、Ubuntu Server_20.04.1_LTS_64位、Ubuntu Server_22.04.1_LTS_64位
﻿
Debian（64位）
Debian_8.2_64位、Debian_9.0_64位、Debian_12.0_64位
﻿
openSUSE（64位）
openSUSE_42.3_64位
LogListener 详细版本功能变更信息请参见 LogListener 版本变更。
网络与端口说明
LogListener 以客户端方式主动连接 CLS 服务端域名上报日志，默认使用 TCP 80（HTTP）；如启用 HTTPS 加密传输，则使用 TCP 443。本地源端口由操作系统从临时端口范围（ephemeral port）中自动分配，无需您手动固定或放通。请确保服务器安全组/防火墙的出站规则允许访问 CLS 服务域名的80/443端口，否则日志将无法上报。
准备工作
需先下载 loglistener_operator 脚本。
内网下载地址：
wget https://mirrors.tencentyun.com/install/cls/script/loglistener/loglistener_operator && chmod u+x loglistener_operator 
外网下载地址：
wget https://mirrors.tencent.com/install/cls/script/loglistener/loglistener_operator && chmod u+x loglistener_operator 
操作步骤
步骤1：安装 LogListener
使用 root 用户执行脚本，命令如下。
使用 SecretId、SecretKey 安装（强鉴权）
安装最新版本
安装指定版本
使用本地 package 安装
指定 URL 安装
# 内网访问
./loglistener_operator install -s ${secret_id} -k ${secret_key} -r ${region}
﻿
# 外网访问
./loglistener_operator install -s ${secret_id} -k ${secret_key} -r ${region} -n internet
# 内网访问
./loglistener_operator install -s ${secret_id} -k ${secret_key} -r ${region} --version ${version}
﻿
# 外网访问
./loglistener_operator install -s ${secret_id} -k ${secret_key} -r ${region} --version ${version} -n internet
注意：
该脚本只支持安装3.4.0以上版本的包。
# 内网访问
./loglistener_operator install -s ${secret_id} -k ${secret_key} -r ${region} --package_path ${package_path}
﻿
# 外网访问
./loglistener_operator install -s ${secret_id} -k ${secret_key} -r ${region} --package_path ${package_path} -n internet
说明：
LogListener 安装包的下载地址格式固定，将 URL 中的版本号替换为所需版本即可。以 x64 架构的 3.6.5 版本为例：
内网：https://mirrors.tencentyun.com/install/cls/packages/loglistener-linux-x64-3.6.5.tar.gz﻿
外网：https://mirrors.tencent.com/install/cls/packages/loglistener-linux-x64-3.6.5.tar.gz﻿
将安装包上传至待安装的服务器，再通过 --package_path 指定安装包的完整路径（含文件名），例如 /root/loglistener-linux-x64-3.6.5.tar.gz。
# 内网访问
./loglistener_operator install -s ${secret_id} -k ${secret_key} -r ${region} --url https://xxx.tar.gz
﻿
# 外网访问
./loglistener_operator install -s ${secret_id} -k ${secret_key} -r ${region} --url https://xxx.tar.gz -n internet
说明：
LogListener 安装包的下载地址格式固定，将 URL 中的版本号替换为所需版本即可。以 x64 架构的 3.6.5 版本为例：
内网：https://mirrors.tencentyun.com/install/cls/packages/loglistener-linux-x64-3.6.5.tar.gz﻿
外网：https://mirrors.tencent.com/install/cls/packages/loglistener-linux-x64-3.6.5.tar.gz﻿
使用 UIN 安装（弱鉴权）
为避免在服务器内配置长期有效的云 API 密钥，LogListener 支持基于账号 UIN 实现弱鉴权接入。您可根据业务安全要求选择弱鉴权安装与 SecretId、SecretKey 密钥安装其中一种方式。弱鉴权不校验请求方的真实身份，存在请求被伪造或重放的风险。请仅在能够接受该风险的场景中使用。对安全性要求较高的业务，建议继续使用 SecretId、SecretKey 或云服务器角色鉴权。
安装步骤
1. 获取当前腾讯云账号的 UIN，并确认日志服务所在地域。
2. 在目标日志主题的基本信息页面，在高级设置中开启匿名上传，并在匿名操作中选择 API/SDK 上传日志。
3. 选择对应的安装方式并执行命令。
安装最新版本
安装指定版本
使用本地 package 安装
指定 URL 安装
# 内网访问
./loglistener_operator install --uin ${uin} -r ${region}
﻿
# 外网访问
./loglistener_operator install --uin ${uin} -r ${region} -n internet
# 内网访问
./loglistener_operator install --uin ${uin} -r ${region} --version ${version}
﻿
# 外网访问
./loglistener_operator install --uin ${uin} -r ${region} --version ${version} -n internet
注意：
该脚本只支持安装3.4.0以上版本的包。
./loglistener_operator install --uin ${uin} -r ${region} --package_path ${package_path}
﻿
# 外网访问
./loglistener_operator install --uin ${uin} -r ${region} --package_path ${package_path} -n internet
说明：
LogListener 安装包的下载地址格式固定，将 URL 中的版本号替换为所需版本即可。以 x64 架构的 3.6.5 版本为例：
内网：https://mirrors.tencentyun.com/install/cls/packages/loglistener-linux-x64-3.6.5.tar.gz﻿
外网：https://mirrors.tencent.com/install/cls/packages/loglistener-linux-x64-3.6.5.tar.gz﻿
将安装包上传至待安装的服务器，再通过 --package_path 指定安装包的完整路径（含文件名），例如 /root/loglistener-linux-x64-3.6.5.tar.gz。
# 内网访问
./loglistener_operator install --uin ${uin} -r ${region} --url https://xxx.tar.gz
﻿
# 外网访问
./loglistener_operator install --uin ${uin} -r ${region} --url https://xxx.tar.gz -n internet
﻿
说明：
LogListener 安装包的下载地址格式固定，将 URL 中的版本号替换为所需版本即可。以 x64 架构的 3.6.5 版本为例：
内网：https://mirrors.tencentyun.com/install/cls/packages/loglistener-linux-x64-3.6.5.tar.gz﻿
外网：https://mirrors.tencent.com/install/cls/packages/loglistener-linux-x64-3.6.5.tar.gz﻿
使用限制
弱鉴权与 SecretId、SecretKey 强鉴权方式互斥，安装时不能同时配置。
本功能适用于 Linux 服务器，暂不支持 Docker、EKS 或 Kubernetes 等容器采集场景。
如果 LogListener 使用本地采集配置，开启弱鉴权后，请将 <安装目录>/conf/user_config/ 下本地 JSON 配置中的 outputs[].detail.Uin 更新为当前账号 UIN，并确保与安装命令中的 --uin 参数一致。
说明：
若主账号已授权协作者日志服务的读写权限，建议使用协作者密钥。
-r 为您所使用的日志服务区域，而非您的业务机器所处的区域。当您所使用的日志服务区域与您的业务机器所处的区域不一致时，请额外配置参数 -network 为 internet，即代表外网访问。
云服务器与日志集同地域的情况下，建议使用内网方式访问服务域名；云服务器与日志集在不同地域的情况下，建议使用外网方式访问服务域名。
关于日志采集权限详情，请参见 LogListener 日志采集权限。
上述两种安装完成后返回结果如下：
﻿
参数说明
参数名
是否必填
描述
-s
使用 SecretId、SecretKey 安装时必填
﻿云 API 密钥 的一部分，SecretId 用于标识 API 调用者身份。请确保云 API 密钥关联的账号具有相应的 LogListener 日志采集权限。
-k
使用 SecretId、SecretKey 安装时必填
﻿云 API 密钥 的一部分，SecretKey 是用于加密签名字符串和服务器端验证签名字符串的密钥。请确保云 API 密钥关联的账号具有相应的 LogListener 日志采集权限。
--uin
使用 UIN 安装（弱鉴权）时必填
腾讯云账号 UIN。该参数与 SecretId、SecretKey 互斥，不能同时配置。
-n
否
表示 LogListener 通过哪种方式访问服务域名，取值：internal 内网访问（默认），internet 外网访问。
内网访问：适用于腾讯云服务器，且服务器所在地域与机器组一致。
外网访问：适用于非腾讯云服务器，或服务器所在地域与机器组不一致。
-r
是
region 表示日志服务所在的 地域，此处填写域名简称，例如 ap-beijing、ap-guangzhou 等。
-d
否
表示日志服务所在地域的 域名。例如 ap-beijing.cls.tencentyun.com、ap-guangzhou.cls.tencentyun.com 等。
注意：
当您所使用的日志服务区域与您的业务机器所处的区域不一致时，请配置外网域名。例如 ap-beijing.cls.tencentcs.com。
-i
否
机器的 IP 地址，机器组可通过所配 IP 地址与该机器关联，详情请参见 机器组。若不填写，LogListener 会自动获取本机的 IP 地址。
-l
否
机器标识，填写后该机器将与同样带有所填机器标识的机器组关联，详情请参见 机器组。多个标识按逗号分隔。
注意：
若配置了机器标识， 该机器将只能通过机器标识与机器组关联， 无法通过 IP 进行关联；若不配置， 机器组只能通过 IP 关联该机器。
-p
否
端口，默认 80。如需使用 HTTPS 加密传输，请指定443。
-u
否
默认不上传机器标识到 CLS。
--base_dir
否
LogListener 安装路径，默认安装在 /opt 目录下。
--package_path
否
使用本地包安装时，指定本地安装包（.tar.gz 文件）的完整路径（需包含文件名），例如 /tmp/loglistener.tar.gz；填写目录路径将无法识别。本地安装包可从 CLS 官方仓库下载，命名格式为 loglistener-linux-<处理器架构>-<版本号>.tar.gz（需使用不带 -update 后缀的全量安装包），详见 安装 LogListener-使用本地 package 安装 中的下载地址。
--url
否
指定 URL 安装时使用，指定 mirrors 仓库的地址。
--version
否
指定版本号安装，默认安装最新版本。
--dynamic_ip
否
用于控制是否开启动态 IP 自动检测能力，默认为 false。若入参为 true，当 IP 发生变更时可实时更新（仅机器标识场景支持，通过 IP 地址关联的场景不支持该能力）。
注意：
仅 LogListener 3.5.7及以上版本支持该参数。
--switch_endpoint
否
启用备用域名。默认为 false，若入参为 true，当主域名网络失败后会使用备用域名。
入参 true 后，配置文件新增 backup_endpoints 字段（备用域名），系统会主动填充备用域名。
若用户为内网访问，backup_endpoints 主动填充为外网。
若用户为外网访问，backup_endpoints 主动填充为内网。
您也可以在配置文件中手动修改备用域名（支持填充多个）。若主域名无法访问，LogListener 会按照备用域名的顺序依次进行访问直至访问成功。
注意：
仅 LogListener 3.5.7及以上版本支持该参数。
--skip_os_support_check
否
仅 LogListener 3.6.4及以上版本支持该参数，开启后将允许在非标 OS 环境跳过系统白名单校验完成安装。
注意：
更多细节可使用 ./loglistener_operator install --help 查看。
﻿
如您需要调整 Loglistener 的配置和密钥，请参见 Loglistener 配置指南。
步骤2：启动 LogListener
systemctl start loglistener
执行 systemctl check loglistener 查看是否启动成功：
﻿
步骤3：加入机器组
完成 LogListener 安装并启动后，需在 日志服务控制台 创建或选择已有 机器组，并将服务器加入机器组中。您可通过以下两种方式将服务器加入机器组：
﻿通过关联机器 IP 地址创建机器组﻿
﻿通过机器标识创建机器组﻿
步骤4：采集日志
将服务器加入机器组后，即可 配置采集服务器上的文本日志。
LogListener 常用操作
版本≥3.4.0
版本<3.4.0
查看 LogListener 版本：需要在 LogListener 的安装目录下（默认安装目录为/opt/loglistener），执行如下命令即可查看版本。
./loglistener -v
查看 LogListener 帮助文档：需要在 LogListener 的安装目录下（默认安装目录为/opt/loglistener），执行如下命令即可查看帮助说明。
./loglistener -h
停止 LogListener：
systemctl stop loglistener
重启 LogListener：
systemctl restart loglistener
执行 systemctl check loglistener 查看是否重启成功。
查看 LogListener 进程状态：
systemctl status loglistener
﻿
检查 LogListener 心跳及配置：
systemctl check loglistener
切换鉴权方式：LogListener 3.6.6 及以上版本支持在 SecretId、SecretKey 强鉴权与 UIN 弱鉴权之间切换。需要在 LogListener 的安装目录下（默认安装目录为/opt/loglistener），执行如下命令即可切换。
# 强鉴权切换为弱鉴权
/opt/loglistener/loglistener convert_auth --auth_mode --uin ${uin} 
﻿
#弱鉴权切换为强鉴权
/opt/loglistener/loglistener convert_auth --auth_mode -s ${secret_id} -k ${secret_key} 
说明：
仅单账号场景支持鉴权切换，多账号场景暂不支持切换鉴权方式。
卸载 LogListener：
1.1 使用 停止命令 systemctl stop loglistener 停止运行旧版本的 LogListener。
systemctl stop loglistener
1.2 需要在 LogListener 的安装目录下（默认安装目录/opt/loglistener），在/opt/loglistener/tools 路径下，以管理员权限执行卸载命令。
./loglistener_operator uninstall
查看 LogListener 版本：
/etc/init.d/loglistenerd -v
查看 LogListener 帮助文档：
/etc/init.d/loglistenerd -h
﻿停止 LogListener
：
通过 systemd 执行。适用于 LogListener 2.8.3以上并且操作系统具有 systemd。
systemctl stop loglistenerd
不通过 systemd 执行。适用于 LogListener 2.8.3以下或者 LogListener 2.8.3以上但是操作系统没有 systemd。
/etc/init.d/loglistenerd stop
重启 LogListener：
通过 systemd 执行。适用于 LogListener 2.8.3以上并且操作系统具有 systemd。
systemctl restart loglistenerd
执行 /etc/init.d/loglistenerd check 查看是否重启成功：
﻿
不通过 systemd 执行。适用于 LogListener 2.8.3以下或者 LogListener 2.8.3以上但是操作系统没有 systemd。
/etc/init.d/loglistenerd restart
重启成功返回样例：
﻿
查看 LogListener 进程状态：
/etc/init.d/loglistenerd status
LogListener 正常情况会运行两个进程：
﻿
检查 LogListener 心跳及配置：
/etc/init.d/loglistenerd check
﻿
修改 LogListener 配置：请参见 LogListener 配置指南。
﻿卸载 LogListener
：
1.1 使用 停止命令 停止运行旧版本的 LogListener。
1.2 以安装路径/usr/local/为例，在/usr/local/loglistener/tools 路径下，以管理员权限执行卸载命令：
./loglistener.sh uninstall
手动更新 LogListener：
复用断点文件（不会重复采集日志）：
1.1 使用 停止命令 停止运行旧版本的 LogListener。
1.2 以安装目录/usr/local/loglistener 为例，前往安装目录下，备份旧版本中的断点文件目录./data。例如：将旧版的断点文件备份至/tmp/loglistener-backup 目录下。
cp -r ./data /tmp/loglistener-backup/
1.3 使用 卸载命令 卸载旧版本的 LogListener。
1.4 ﻿下载并安装 最新版本的 LogListener。
1.5 以安装目录/usr/local/loglistener 为例，复制所备份的断点文件目录（步骤2）到新版本 LogListener 目录下。
cp -r /tmp/loglistener-backup/data ./
1.6 使用 启动命令 启动运行新版本 LogListener。
不复用断点文件（可能会重复采集日志）：
1.7 使用 停止命令 停止运行旧版本的 LogListener。
1.8 使用 卸载命令 卸载旧版本的 LogListener。
1.9 ﻿下载并安装最新版本 的 LogListener。
1.10 使用 启动命令 启动运行新版本 LogListener。
升级指南
参考 LogListener 升级指南 即可。

处理器架构	操作系统类别	确定可安装环境
x64/ARM	TencentOS Server	TencentOS Server 3.1、TencentOS Server 2.4
		CentOS（64位）	CentOS_6.8_64位、CentOS_6.9_64位、CentOS_7.2_64位、CentOS_7.3_64位、CentOS_7.4_64位、CentOS_7.5_64位、CentOS_7.6_64位、CentOS_8.0_64位
		Ubuntu（64位）	Ubuntu Server_14.04.1_LTS_64位、Ubuntu Server_16.04.1_LTS_64位、Ubuntu Server_18.04.1_LTS_64位、Ubuntu Server_20.04.1_LTS_64位、Ubuntu Server_22.04.1_LTS_64位
		Debian（64位）	Debian_8.2_64位、Debian_9.0_64位、Debian_12.0_64位
		openSUSE（64位）	openSUSE_42.3_64位

参数名	是否必填	描述
-s	使用 SecretId、SecretKey 安装时必填	云 API 密钥的一部分，SecretId 用于标识 API 调用者身份。请确保云 API 密钥关联的账号具有相应的 LogListener 日志采集权限。
-k	使用 SecretId、SecretKey 安装时必填	云 API 密钥的一部分，SecretKey 是用于加密签名字符串和服务器端验证签名字符串的密钥。请确保云 API 密钥关联的账号具有相应的 LogListener 日志采集权限。
--uin	使用 UIN 安装（弱鉴权）时必填	腾讯云账号 UIN。该参数与 SecretId、SecretKey 互斥，不能同时配置。
-n	否	表示 LogListener 通过哪种方式访问服务域名，取值：internal 内网访问（默认），internet 外网访问。内网访问：适用于腾讯云服务器，且服务器所在地域与机器组一致。外网访问：适用于非腾讯云服务器，或服务器所在地域与机器组不一致。
-r	是	region 表示日志服务所在的地域，此处填写域名简称，例如 ap-beijing、ap-guangzhou 等。
-d	否	表示日志服务所在地域的域名。例如 ap-beijing.cls.tencentyun.com、ap-guangzhou.cls.tencentyun.com 等。注意：当您所使用的日志服务区域与您的业务机器所处的区域不一致时，请配置外网域名。例如 ap-beijing.cls.tencentcs.com。
-i	否	机器的 IP 地址，机器组可通过所配 IP 地址与该机器关联，详情请参见机器组。若不填写，LogListener 会自动获取本机的 IP 地址。
-l	否	机器标识，填写后该机器将与同样带有所填机器标识的机器组关联，详情请参见机器组。多个标识按逗号分隔。注意：若配置了机器标识，该机器将只能通过机器标识与机器组关联，无法通过 IP 进行关联；若不配置，机器组只能通过 IP 关联该机器。
-p	否	端口，默认 80。如需使用 HTTPS 加密传输，请指定443。
-u	否	默认不上传机器标识到 CLS。
--base_dir	否	LogListener 安装路径，默认安装在 /opt 目录下。
--package_path	否	使用本地包安装时，指定本地安装包（`.tar.gz` 文件）的完整路径（需包含文件名），例如 `/tmp/loglistener.tar.gz`；填写目录路径将无法识别。本地安装包可从 CLS 官方仓库下载，命名格式为 `loglistener-linux-<处理器架构>-<版本号>.tar.gz`（需使用不带 `-update` 后缀的全量安装包），详见安装 LogListener-使用本地 package 安装中的下载地址。
--url	否	指定 URL 安装时使用，指定 mirrors 仓库的地址。
--version	否	指定版本号安装，默认安装最新版本。
--dynamic_ip	否	用于控制是否开启动态 IP 自动检测能力，默认为 false。若入参为 true，当 IP 发生变更时可实时更新（仅机器标识场景支持，通过 IP 地址关联的场景不支持该能力）。注意：仅 LogListener 3.5.7及以上版本支持该参数。
--switch_endpoint	否	启用备用域名。默认为 false，若入参为 true，当主域名网络失败后会使用备用域名。入参 true 后，配置文件新增 backup_endpoints 字段（备用域名），系统会主动填充备用域名。若用户为内网访问，backup_endpoints 主动填充为外网。若用户为外网访问，backup_endpoints 主动填充为内网。您也可以在配置文件中手动修改备用域名（支持填充多个）。若主域名无法访问，LogListener 会按照备用域名的顺序依次进行访问直至访问成功。注意：仅 LogListener 3.5.7及以上版本支持该参数。
--skip_os_support_check	否	仅 LogListener 3.6.4及以上版本支持该参数，开启后将允许在非标 OS 环境跳过系统白名单校验完成安装。

LogListener 安装指南（Linux 版）

本页目录：

安装环境

网络与端口说明

准备工作

操作步骤

步骤1：安装 LogListener

使用 SecretId、SecretKey 安装（强鉴权）

使用 UIN 安装（弱鉴权）

安装步骤

使用限制

参数说明

步骤2：启动 LogListener

步骤3：加入机器组

步骤4：采集日志

LogListener 常用操作

升级指南