IBM Cloud Docs
管理 Logpush 作业

管理 Logpush 作业

IBM Cloud® Internet Services 企业级计划可以访问、DNS和Range请求的详细日志,以及其域的防火墙事件。HTTP 这些日志有助于调试和分析,尤其是在与其他数据源(如原点的入口或应用服务器日志)相结合时。

准备工作

在使用用户界面创建Logpush任务之前,请查看以下信息并满足所有前提条件:

  • 目前,CIS 用户界面支持以下目的地:

    • IBM Cloud Logs
    • Cloud Object Storage
    • Splunk
  • 在使用Logpush之前,请务必 启用日志保留功能

  • 如果使用 Cloud Object Storage,您必须拥有一个 Cloud Object Storage 实例,且该实例的存储桶具有对象写入器访问权限,该权限已授予 IBM Cloud 账户 cislogp@us.ibm.com。 这样,CIS 就可以将请求日志写入 Cloud Object Storage 存储桶。

  • 来自 Logpush 的数据与来自 Logpull 的数据相同。 然而,与Logpull(允许您下载请求日志)不同,Logpush(允许您将请求日志推送到目标位置)。

  • DNS、范围和防火墙事件日志不包含在 HTTP / HTTPS 日志中,需要单独处理。 这些工作可以发送到同一个目的地。 但是,当使用 Cloud Object Storage 时,您需要指定不同的路径。

  • Logpush使用 Cloud Object Storage 的公开可访问 HTTPS 端点,确保日志数据在传输过程中得到加密。

  • 当发送日志到 Splunk 时,CIS 会检查IP地址的可访问性和端口,然后验证 HTTP 接收日志源的证书。 如果所有参数都有效,则创建一个Logpush。 然后,Logpush开始向 HTTP 事件收集器( Splunk )发送事件。

  • 如果您的目的地未得到 CIS 的明确支持,则Logpush仍可通过自定义 HTTP 目的地访问。 这包括您自己的自定义 HTTP 日志服务器。

    为避免出错,请确保目标地址可以接受名为 test.txt.gz 的gzipped文件上传,其中包含压缩内容 {"content":"tests"}

  • 使用 Cloud Object Storage 时,您必须在创建Logpush作业后验证所有权。 这项任务将在以下程序中描述。

在控制台中创建 Logpush 作业

要在控制台中创建 Logpush 作业,请按照以下步骤操作:

  1. 选择 “账户” > “日志”,然后点击 “创建”。

  2. 选择服务:

    1. 从可用选项中选择所需的服务类型。
    2. 选择数据集类型。
    3. 可选:输入描述和名称。
    4. 选择下一步
  3. 配置目的地:

    IBM Cloud Logs

    输入 IBM Cloud 日志实例ID、实例区域和API密钥(用户管理)。

    需要 IBM Cloud 日志实例所在账户的 API 密钥。 您可以使用用户API密钥或服务ID API密钥。 此密钥用于为Logpush作业生成一个无记名令牌。 API 密钥可通过使用 更新日志推送作业 API 进行轮换。

    对于 IBM Cloud 日志服务,用户或服务ID必须被授予发送者 IAM角色。

    Cloud Object Storage

    输入 Cloud Object Storage 实例、存储桶信息(名称和区域)以及存储桶路径(可选)。 然后将日志整理到每日文件夹中(可选)。

    Cloud Object Storage 的终点值必须唯一。 建议使用桶状路径以避免冲突。

    Splunk
    输入 Splunk 终端、频道ID和认证令牌。

    您可以选择使用不安全的验证方式,但并不推荐这样做。

    自定义 HTTP 目的地

    输入您的 HTTP 终端。

    请确保端点已正确进行 URL 编码,且任何必要的请求头已添加为 URL 参数,格式为“header_*”(例如 header_Authorization )。

  4. 仅限 Cloud Object Storage 职位,请验证所有权。 为此,请下载您存储桶中的文件,然后将令牌粘贴到所有权令牌文本区域中。 然后,单击下一步

    您可以从“故障排除”部分重新发送文件,如果文件桶路径不正确,也可以返回上一步。

  5. 选择日志字段:

    1. 验证 Logpush 详细信息是否正确。

    2. 从“时间戳格式”和“频率”菜单中选择Logpush设置。

    3. 选择是否启用Logpush作业,将启用开关切换到“开启” 即可。

    4. 选择要包含在Logpush任务中的日志字段。

      您可以使用切换按钮选择所有字段展开所有字段。 您也可以恢复到默认设置。

    5. 点击 “完成” 创建您的Logpush任务。

从命令行界面创建Logpush任务

您可以使用 ibmcloud cis logpush-job-create CLI创建Logpush任务。

要为特定域创建Logpush作业并启用该作业,请运行以下命令:

ibmcloud cis logpush-job-create DNS_DOMAIN_ID --destination PATH --name JOB_NAME --fields all --enable true

其中:

-destination:指定目标路径。 支持的目的地路径如下:

IBM Cloud 日志路径
IBM Cloud Logs
ibmcl://<INSTANCE_ID>.ingress.<REGION>.logs.cloud.ibm.com/logs/v1/singles?ibm_api_key=<IBM_API_KEY>

例如需要设置 日志实例的账户的 API 密钥。
ibmcl://604a309c-585c-4a42-955d-76239ccc1905.ingress.us-south.logs.cloud.ibm.com/logs/v1/singles?ibm_api_key=zxzeNQI22dPwxxxxxxxx9jxdtn1EVK

IBM Cloud 您可以使用用户API密钥或服务ID API密钥。 此密钥用于为Logpush作业生成一个无记名令牌。 API 密钥可通过使用更新日志推送作业 API 进行轮换。

重要: 用户或服务 ID 必须在 IBM Cloud 日志服务上被授予发送方 IAM 角色。

Cloud Object Storage 路径
Cloud Object Storage
cos://<BUCKET_OBJECT_PATH>?region=<REGION>&instance-id=<IBM_ClOUD_OBJECT_STORAGE_INSTANCE_ID>

例如:
cos://cis-test-bucket/logs?region=us&instance-id=f75e6d90-4212-4026-851c-d572071146cd

自定义 HTTP 路径
自定义 HTTP
https://<HOSTNAME>?header_Authorization=Basic%20REDACTED&tags=host:<DOMAIN_NAME>,dataset:<LOGPUSH_DATASET>

例如:
https://logs.example.com?header_Authorization=a64Vxxxxx5Aq

--name:指定 Logpush 任务名称。

--fields:指定要包含在日志文件中的日志字段列表。 使用逗号分隔多个字段。 使用 ibmcloud cis logpush-available-fields DNS_DOMAIN_ID --dataset DATASET 命令可获得可用日志字段的完整列表,或使用 all 命令将所有可用字段包含在日志文件中。

--enable:是启用或禁用 Logpush 作业的标志。 有效值为 truefalse (默认值)。

Cloud Object Storage:验证所有权

创建Logpush任务将日志发送至 Cloud Object Storage 后,您必须验证所有权。

当挑战令牌写入指定 Cloud Object Storage 存储桶中的文件时,请按照以下步骤操作:

  • 从您的 Cloud Object Storage 存储空间下载文件并打开。
  • 从文件中复制挑战令牌,并将其粘贴到命令提示符中,以解决所有权挑战。

在 CIS 验证所有权挑战后,Logpush作业成功创建。 然后,该任务将每30秒或达到100,000条记录时(以先到者为准)将请求日志推送到您的 Cloud Object Storage 存储桶中。 请注意,在30秒内或每10万条记录中可能会推送多个文件。

您还可以使用桶路径中的 {DATE} 令牌将 Logpush 日志整理到每日文件夹中。 例如: cos://mybucket/cislog/{DATE}?region=us-south&instance-id=c84e2a79-ce6d-3c79-a7e4-7e7ab3054cfe

命令示例

CLI示例支持的目的地:

IBM Cloud Logs

示例

ibmcloud cis logpush-job-create 601b728b86e630c744c81740f72570c3 --destination "ibmcl://604a309c-585c-4a42-955d-76239ccc1905.ingress.us-south.logs.cloud.ibm.com/logs/v1/singles?ibm_api_key=xxxxxxxx" --name logpushJobGen --enable true --fields RayID --dataset http_requests --frequency high -i 1a9174b6-0106-417a-844b-c8eb43a72f63
Cloud Object Storage

示例

ibmcloud cis logpush-job-create 31984fea73a15b45779fa0df4ef62f9b --destination cos://cis-test-bucket/logs?region=us&instance-id=f75e6d90-4212-4026-851c-d572071146cd --name logpushcreate --enable true --fields all --timestamps rfc3339 --dataset http_requests --frequency low -i cis-demo --output JSON
自定义 HTTP

示例

ibmcloud cis logpush-job-create 601b728b86e630c744c81740f72570c3 --destination https://logs.example.com?header_Authorization=a64VuywesDu5Aq" --name logpushJobGen --enable true --fields RayID --dataset http_requests --frequency high -i 1a9174b6-0106-417a-844b-c8eb43a72f63

使用 API 创建 Logpush 作业

当使用 IBM Cloud、Cloud Object Storage 或 Splunk 时,您可以使用 创建Logpush作业API 来创建Logpush作业。

使用API获取数据集的可用日志字段

日志字段可以在Logpush作业的 logpull_options 中指定,以自定义发送到目的地的内容。 要获取Logpush数据集的可用日志字段,请按照以下步骤操作:

  1. 使用正确的变量设置 API 环境。

  2. 在变量中存储以下值,以便在 API 命令中使用:

    CRN:服务实例的完整 URL 编码CRN。

    ZONE_ID:域名 ID。

    DATASET:正在检查Logpush数据集。 http_requests, range_events, dns_logs, firewall_events 中的一个。

  3. 启动所有变量后,创建 Logpush 作业:

    curl -X GET https://api.cis.cloud.ibm.com/v2/$CRN/zones/$ZONE_ID/logpush/datas/$DATASET/fields \
    --header "Content-Type: application/json" \
    --header "X-Auth-User-Token: Bearer $IAM_TOKEN"'
    

创建一个Logpush任务,将日志发送到您的目的地

要创建一个目标为( IBM Cloud 日志、Cloud Object Storage 或 Splunk )的 Logpush 作业,请按照以下步骤操作:

  1. 使用正确的变量设置 API 环境。

  2. 在变量中存储以下值,以便在 API 命令中使用:

    CRN:服务实例的完整 URL 编码云资源名称(CRN)。

    ZONE_ID:域名 ID。

    --request body:创建Logpush作业正文的信息( logpush_job_DESTINATION_req ),其中 DESTINATION 为以下值之一:

    IBM Cloud 记录目的地
    IBM Cloud Logs

    ibmcl:用于标识推送数据的 IBM Cloud 日志实例的信息。 ibmcl 对象中的字段包括:

    • instance_id : IBM Cloud 日志实例的ID。
    • region : IBM Cloud 日志实例的区域(例如, us-south )。
    • api_key :需要设置 IBM Cloud 日志实例的帐户的API密钥。 您可以使用用户API密钥或服务ID API密钥。 此密钥用于为Logpush作业生成一个无记名令牌。 API密钥可通过更新Logpush作业API 进行轮换。

    重要提示: 必须在 IBM Cloud 日志服务上为用户或服务ID授予发送者I AM角色。

    ibmcl_names : 可选字段,用于自定义 IBM Cloud 日志中使用的应用程序和子系统名称。 ibmcl_names 对象中的字段包括:

    • application_name :作业的自定义应用程序名称。
    • subsystem_name :作业的自定义子系统名称。
    Cloud Object Storage 目的地
    Cloud Object Storage

    cos:用于识别数据推送的 Cloud Object Storage 存储桶的信息。 cos 对象中的字段包括:

    • bucket_name :发送日志的COS存储桶名称(例如: cos-bucket001 )。
    • region : Cloud Object Storage 实例的区域(例如: us-south )。
    • id :COS实例的ID。
    Splunk 目的地
    Splunk

    splunk:用于识别 Splunk HTTP Event Collector (HEC)的信息,数据将推送到该位置。 splunk 对象中的字段包括:

    • endpoint_url : URL 的 Splunk HEC。
    • channel_id :用于唯一标识日志推送的随机GUID。
    • skip_verify :用于跳过 HTTP 事件收集器证书验证的布尔标志。 仅当HEC使用自签名证书时,才将此设置为 true
    • source_type : Splunk 源类型(例如: cloudflare:json )。
    • auth_token : Splunk 授权令牌。
    自定义 HTTP 目的地
    自定义 HTTP
    destination_conf:用于配置自定义 HTTP 目标的信息,数据将推送到该目标。 日志推送(Logpush)可以使用以 header_ 为前缀的查询参数指定标题(例如:header_Authorization=XXXX )。

    name:Logpush 工作的名称。

    enabled:工作是否已启用。 truefalse

    logpull_options:配置字符串。 例如,fields=RayID,ZoneID&timestamps=rfc3339

    dataset:提取的数据集。 http_requests, dns_logs, range_events, firewall_events 中的一个。

    frequency: CIS 向目的地发送成批日志的频率。 highlow

  3. 启动所有变量后,创建 Logpush 作业:

    IBM Cloud Logs

    curl -X POST https://api.cis.cloud.ibm.com/v2/$CRN/zones/$ZONE_ID/logpush/jobs \
    --header "Content-Type: application/json" \
    --header "X-Auth-User-Token: Bearer $IAM_TOKEN" \
    --data '{
       "ibmcl": {
          "instance_id": "f8k3309c-585c-4a42-955d-76239cccf8k3",
          "region": "us-south",
          "api_key": "f8k3NQI22dPwNVCcmS62YFL1tm9vaehY6C9jxdtnf8k3"
       },
       "ibmcl_names": {
          "application_name": "cis-edge-logs",
          "subsystem_name": "stage-firewall-logs"
       }
       "dataset": "http_requests",
       "enabled": true,
       "logpull_options": "fields=RayID,ZoneID&timestamps=rfc3339",
       "name": "CIS-Edge-Requests",
       "frequency": "low"
    }'
    

    Cloud Object Storage

    curl -X POST https://api.cis.cloud.ibm.com/v2/$CRN/zones/$ZONE_ID/logpush/jobs \
    --header "Content-Type: application/json" \
    --header "X-Auth-User-Token: Bearer $IAM_TOKEN" \
    --data '{
       "cos": {
          "bucket_name": "example_bucket",
          "path": "temp/",
          "id": "cos_instance_id",
          "region": "us-east"
       },
       "dataset": "firewall_events",
       "enabled": false,
       "name": "CIS-Firewall-COS",
       "frequency": "low",
       "logpull_options": "fields=RayID,ZoneID&timestamps=rfc3339",
       "ownership_challenge": "xxxxxxx"
    }'
    

    Splunk

    curl -X POST https://api.cis.cloud.ibm.com/v2/$CRN/zones/$ZONE_ID/logpush/jobs \
    --header "Content-Type: application/json" \
    --header "X-Auth-User-Token: Bearer $IAM_TOKEN" \
    --data '{
       "splunk": {
          "endpoint_url": "example.splunkcloud.com:8088/services/collector/raw",
          "channel_id": "def3c136-7a01-4655-b17f-8e25a780ef2c",
          "skip_verify": false,
          "source_type": "cloudflare:json",
          "auth_token": "Splunk fake3585-0f38-4d62-8b43-c4b78584fake"
       },
       "dataset": "http_requests",
       "enabled": true,
       "name": "CIS-Splunk-Logpush",
       "frequency": "high",
       "logpull_options": "fields=RayID,CacheResponseBytes,CacheResponseStatus,CacheCacheStatus&timestamps=rfc3339"
    }'
    

    自定义 HTTP

    curl -X POST https://api.cis.cloud.ibm.com/v2/$CRN/zones/$ZONE_ID/logpush/jobs \
    --header "Content-Type: application/json" \
    --header "X-Auth-User-Token: Bearer $IAM_TOKEN" \
    --data '{
       "destination_conf": "https://logs.example.com?header_Authorization=a64VuywesDu5Aq",
       "dataset": "http_requests",
       "enabled": true,
       "name": "CIS-Custom-Logpush",
       "frequency": "high",
       "logpull_options": "fields=RayID,CacheResponseBytes,CacheResponseStatus,CacheCacheStatus&timestamps=rfc3339"
    }'