Importing and Exporting Log Source Configurations

Export a region’s log sources as a single YAML file, edit it, then import it back to create or update many sources in one reviewed change. Every import is previewed and validated before anything is written.

When to use it

Use the Log Sources form for one-off edits to a single source. Use Import/Export when you need to:

Step 1 — Export a reference YAML file

Open Log Management → Log Sources, pick the region, then click Export.

Step 1a — Export button in Log Sources

Export scope

• If you select rows first, only those sources are exported.
• If nothing is selected, all sources in the region are exported.

Step 1b — Export scope (selected rows vs all)

The file downloads as YAML. It is a snapshot (editing it changes nothing until you import it).

Sample export file (reference)

This sample file can be used as a guide when creating or editing log sources.

Step 1c — Example exported YAML file

Step 2 — Understand the YAML structure

At the top level you’ll see four keys. Only log_sources is actually imported.

Collector inventory (available_collectors)

Collectors are written as IP addresses in each entry. On import, any collector IP that does not exist in the target region is a blocking error.

The YAML includes a reference list like:

available_collectors:
  - {hostname: SF-01, ip: 192.168.33.54, status: active}
  - {hostname: SF-02, ip: 192.168.33.58, status: active}

Step 3 — Know what the file controls (create vs update)

Identity is identifier_tag (not name, not row id)

Within the region you import into:

collectors is the deployment list (authoritative)

The file decides exactly where the source is deployed:

Everything else is an overwrite

• Any advanced option you omit returns to its default.
• Any unknown parameter name is an error (typos are rejected, not silently ignored).

Step 4 — Use the correct entry shape (by source type)

Every log source entry shares the same outer structure:

- name: Human-readable label          # safe to change
  identifier_tag: unique-tag          # identity for matching
  description: null
  query_tags: []                      # e.g. [env=prod, team=platform]
  source_type: file                   # file | syslog | winevtlog | api_source
  parser: JSON
  collectors: [192.168.33.54]         # required on every entry
  source_parameters:
    base:      # required fields for the type
    advanced:  # tunables (uncomment only what you change)
  routing_rules:                      # optional (Step 5)

Parser names are matched loosely (case/spaces/dashes ignored), so RFC 5424 and syslog-rfc5424 are treated the same. Built-ins include: JSON, Key Value, RFC 5424, RFC 3164, plain. Use parser: null for winevtlog (already structured).

4.1 — source_type: file  (tail files on disk)

- name: OG-LOGS
  identifier_tag: jsonlogs
  source_type: file
  parser: JSON
  collectors: [192.168.33.54]
  source_parameters:
    base:
      file_path: C:\Logs\app
      file_pattern: '*.log'
    advanced:
      ignore_older: 24h
      read_from_head: true
      refresh_interval: 30
      memory_buffer_limit: 32M
      skip_long_lines: 'on'

Notes:

• Quote patterns like *.log (YAML treats * specially).
• Windows paths don’t need escaping; use unquoted or single-quoted strings.

4.2 — source_type: syslog  (listen on a port)

- name: RFC5424
  identifier_tag: rfc5424
  source_type: syslog
  parser: RFC 5424
  collectors: [192.168.33.54]
  source_parameters:
    base:
      mode: tcp        # tcp|udp
      port: 5141       # 1–65535; must be free on each listed collector

Ports are commonly the blocking issue. Validation checks:

• against existing syslog sources in the region, and
• against other entries within the same file.

4.3 — source_type: winevtlog  (remote Windows event logs)

Remote collection uses host blocks under remote_details. Each existing host has a block_id (minted by the system).

- name: Domain Controllers
  identifier_tag: dc-events
  source_type: winevtlog
  parser: null
  collectors: [192.168.33.58]
  source_parameters:
    base:
      remote_windows_host: true
      remote_details:
        - block_id: CNcOQ
          channels: Application,Setup
          domain: ceburu.local
          username: Administrator
          ip: [192.168.33.2]
        - channels: System
          domain: ceburu.local
          username: svc_logs
          ip: [192.168.33.9]
          password: new-pass

Rules:

• Exports never contain passwords.
• New hosts must include password.
• Removing a host block stops collecting from that host (warned).
• remote_details cannot be empty while remote_windows_host: true.

4.4 — source_type: winevtlog  (local Windows event logs on the collector)

- name: Local Windows Events
  identifier_tag: winevt-local
  source_type: winevtlog
  parser: null
  collectors: [192.168.33.58]
  source_parameters:
    base:
      remote_windows_host: false
      channels: Application,Security,System

This is also how you convert a remote source to local: set remote_windows_host: false, remove remote_details, and provide channels.

4.5 — source_type: api_source  (ingest via API, no collectors)

- name: Semantic Search Test
  identifier_tag: semantic-search
  source_type: api_source
  parser: plain
  collectors: []
  source_parameters:
    base: {}

collectors must be an empty list; listing a collector IP is a blocking error.

Step 5 — (Optional) Routing and masking rules

routing_rules has the same shape for every source type:

routing_rules:
  masking_enabled: true
  tag_based_routing: false
  filtering_rule_operator: AND   # AND|OR
  filtering_rules:
    - {field: $service_name, operator: equals, value: 'checkout'}
    - {field: $hostname, operator: not_equals, value: 'staging-01'}
    - {field: $channel, operator: contains, value: [email, ticket]}

Supported operators: equals, not_equals, contains, not_contains, matches_regex, not_matches_regex (aliases like eq, neq, in, regex are accepted).

Step 6 — Import and Validate (preview only)

Go to the region you want to import into, then open Log Sources → Import.

Step 6 — Import entry point (Import button / panel)

Upload the YAML file.

Step 6 — Upload YAML file

Click Validate to preview what will happen.

Step 6 — Import panel with Validate and preview

Nothing is written during validation. The preview shows:

Fix issues, re-upload, and validate again until there are zero errors.

Step 7 — Errors vs warnings (how to read the preview)

Step 7 — Example preview showing errors and warnings

Step 8 — Continue import (writes changes)

When the preview shows 0 errors, click Continue import to apply the plan.

Step 8 — Continue import confirmation

What happens:

1. Each entry is written transactionally (all-or-nothing per entry).
2. Collector configurations are rebuilt for impacted machines.
3. A deployment run starts; sources move through statuses until deployed (API sources may complete immediately).

Clone a region (most common workflow)

1. Export from the source region (select only the sources you want first).
2. Open the target region and note its available collectors (from the Import panel).
3. Edit the YAML:
   • swap collectors IPs for the target region
   • update file paths (often differ)
   • verify syslog ports are free
4. Decide whether to keep identifier_tag the same (same identity in the new region).
5. For remote winevtlog, remove block_id values and add passwords for new host blocks (credentials don’t travel).
6. Import → Validate (expect mostly “create”).
7. Continue import, then delete any file that contains passwords.

Limits and guardrails