HTTP

Synopsis

Creates an HTTP server that accepts messages via HTTP POST requests. Supports multiple authentication methods, TLS encryption, and customizable response handling.

Schema

- id: <numeric>
  name: <string>
  description: <string>
  type: http
  tags: <string[]>
  pipelines: <pipeline[]>
  status: <boolean>
  properties:
    protocol: <string>
    address: <string>
    port: <numeric>
    url: <string>
    content_type: <string>
    timezone: <string>
    reuse: <boolean>
    workers: <numeric>
    response:
      code: <numeric>
      body: <string>
      content_type: <string>
    tls:
      status: <boolean>
      cert_name: <string>
      key_name: <string>
      passphrase: <string>
      min_tls_version: <string>
      max_tls_version: <string>
      client_ca_name: <string>
      client_auth_required: <boolean>
      insecure_skip_verify: <boolean>
    authentication:
      type: <string>
      username: <string>
      password: <string>
    tokens:
      - token: <string>
        tenant_id: <string>
        expire_date: <numeric>
    header:
      key: <string>
      value: <string>
    hmac:
      type: <string>
      header: <string>
      key: <string>
      prefix: <string>

Configuration

The following fields are used to define the device:

Device

Field	Required	Default	Description
`id`	Y		Unique identifier
`name`	Y		Device name
`description`	N	-	Optional description
`type`	Y		Must be `http`
`tags`	N	-	Optional tags
`pipelines`	N	-	Optional pre-processor pipelines
`status`	N	`true`	Enable/disable the device

Protocol

Field	Required	Default	Description
`protocol`	N	`"tcp"`	Transport protocol (typically `tcp`).
`address`	N	`"0.0.0.0"`	Listen address
`port`	Y		Listen port
`url`	N	`"/"`	URL path to listen on
`content_type`	N	`"application/json"`	Expected content type of incoming requests

Response

Field	Required	Default	Description
`response.code`	N	`200`	HTTP response status code
`response.body`	N	`{"message":"success"}`	Response body content
`response.content_type`	N	`"application/json"`	Response content type

Authentication

Field	Required	Default	Description
`authentication.type`	N	`"none"`	Authentication type (`basic`, `bearer`, `header`, or `hmac`)
`authentication.username`	Y*		Username for basic auth
`authentication.password`	Y*		Password for basic auth
`tokens`	Y*	-	Array of accepted bearer tokens. Each entry is a plain string or an object (see Multi-Tenancy).
`header.key`	Y*		Header name for header auth
`header.value`	Y*		Header value for header auth
`hmac.type`	Y*		HMAC algorithm (`sha1`, `sha256` or `sha512`)
`hmac.header`	Y*		Header name for HMAC signature
`hmac.key`	Y*		Secret key for HMAC calculation
`hmac.prefix`	N	-	Optional prefix to strip from HMAC header value

* = Required when authentication.type is set to the corresponding method (tokens when it is bearer).

With bearer, the Authorization: Bearer <token> header (a bare token is also accepted) is matched against tokens. An empty tokens list rejects every request.

With hmac, the header named in hmac.header carries the hex digest of the request body, signed with hmac.key, after hmac.prefix when one is set (for example sha1=), which is stripped first. hmac.type is matched case-insensitively, so SHA1 works as well. sha1 is there for senders that sign with HMAC-SHA1, such as GitHub's legacy X-Hub-Signature header. Any other hmac.type, or none, is not reported as a configuration error: the device starts and refuses every request with 401.

Multi-Tenancy

Each entry in the tokens list may be a plain string (matched as-is, with no tenant) or an object that binds the token to a tenant and an optional expiry. Both forms can be mixed in the same list.

Field	Required	Default	Description
`tokens[].token`	Y		The accepted token secret. Quote long numeric-looking values to preserve them exactly.
`tokens[].tenant_id`	N	-	Tenant identifier attached to records authenticated with this token. Omit for no tenant.
`tokens[].expire_date`	N	never	Expiry as epoch seconds (e.g. `1924905600`). The token is rejected at and after this instant. Omit for a token that never expires.

A request presenting an expired or unknown token is rejected with 401 and no record is ingested. When a request authenticates with a token that carries a tenant_id, that tenant is written to _vmetric.event.tenant_id; the client IP always stays at _vmetric.event.request. Use _vmetric.event.tenant_id to route or isolate each customer's data downstream (see Routes).

tokens:
  - token: "acme-9f3c...key"
    tenant_id: "acme"
    expire_date: 1924905600
  - token: "globex-7a1b...key"
    tenant_id: "globex"
  - "legacy-plain-token"

note

Token changes take effect on the next collector restart.

Requires authentication.type: bearer.

TLS

Field	Required	Default	Description
`tls.status`	N	`false`	Enable TLS encryption
`tls.cert_name`	Y*	`cert.pem`	TLS certificate
`tls.key_name`	Y*	`key.pem`	TLS private key
`tls.passphrase`	N	-	Passphrase for an encrypted private key
`tls.min_tls_version`	N	`tls1.2`	Minimum accepted TLS version (`tls1.0`, `tls1.1`, `tls1.2`, `tls1.3`)
`tls.max_tls_version`	N	-	Maximum accepted TLS version. When unset, the highest mutually supported version is negotiated.
`tls.client_ca_name`	N	-	CA bundle used to verify client certificates (mTLS)
`tls.client_auth_required`	N**	`false`	Require connecting clients to present a valid certificate. When `false`, a client certificate is verified only if one is presented.
`tls.insecure_skip_verify`	N	`false`	Has no effect on a listener. It applies only where the Director connects to a server, never to the connections it accepts: a client certificate is checked only through `tls.client_ca_name` and `tls.client_auth_required`. Changing it restarts the listener and nothing else.

* = Required when tls.status is true.

** = Requires tls.client_ca_name. If tls.client_auth_required is true or tls.client_ca_name is set and the named CA cannot be loaded, the configuration is rejected and the device fails to start.

note

tls.min_version is a deprecated alias for tls.min_tls_version, honored only when tls.min_tls_version is unset. Use tls.min_tls_version in new configurations.

note

TLS material fields (cert_name, key_name, ca_name, client_ca_name) accept any of the following:

File name — resolved relative to the service root directory. Nested paths such as certs/prod/server.pem are supported.
Absolute path — honored only if it resolves inside the service root. Any path that escapes the root is refused.
Inline PEM content — used verbatim when the value contains -----BEGIN.
Environment variable — ${ENV_VAR}.
Vault reference — $secret{id=...} or $secret{store=...,ref=...}.

Advanced Configuration

To enhance performance and achieve better message handling, the following settings are used.

Performance

Field	Required	Default	Description
`timezone`	N	-	Per-device timestamp offset adjustment
`reuse`	N	`true`	Enable socket address reuse
`workers`	N	Scales with CPU count	Number of worker processes: `1` up to 16 cores, `2` up to 32, `3` up to 64, `4` beyond. Never more than `4` — an explicit higher value is clamped — and reduced further on memory-constrained hosts.
`max_buffer_size`	N	`128MB`	Ingest buffer admission cap. Also sizes this listener's ingest buffers: 3/8 of this value at start, growing to at most 3x

note

flush_interval and queue.interval are Director service-level settings configured in vmetric.yml and cannot be overridden per device. max_buffer_size is the exception: it has a service-level default that a device can override.

note

max_buffer_size is the ingest-buffer admission cap, and is distinct from any buffer_size field above, which sizes the network read buffer. Left unset it is 128MB, whose buffers take 48 MiB of heap per listener worker at start and grow to at most 384 MiB as bursts need the room — and with reuse: true a device runs one worker per listener. Size strings are binary, and 32MB and 32MiB are exact synonyms.

See Listener Memory Sizing for the arithmetic, the sizing table, and what happens when the cap is exhausted.

Examples

The following are commonly used configuration types.

Basic

Minimal HTTP listener on port 8080 accepting JSON POST requests at /logs:

Create a simple HTTP server...

devices:
  - id: 1
    name: basic_http
    type: http
    properties:
      port: 8080
      url: "/logs"
      content_type: "application/json"
      response:
        code: 200
        body: '{"status":"ok"}'

Authentication

HTTP server with basic auth...

devices:
  - id: 2
    name: auth_http
    type: http
    properties:
      port: 8080
      url: "/api/logs"
      authentication:
        type: "basic"
        username: "vmetric"
        password: "P@ssw0rd"

API Keys

HTTP server using header-based API key authentication:

HTTP server with API key header auth...

devices:
  - id: 3
    name: apikey_http
    type: http
    properties:
      port: 8080
      url: "/api/v1/logs"
      authentication:
        type: "header"
      header:
        key: "X-API-Key"
        value: "${API_KEY}"

Multi-Tenant Bearer Tokens

A single endpoint serving multiple customers, each authenticating with its own bearer token. The matched token's tenant_id is attached to every record for downstream routing:

One HTTP listener accepting many tenants, one token each, one with an expiry...

devices:
  - id: 6
    name: saas_http
    type: http
    properties:
      port: 8088
      authentication:
        type: bearer
      tokens:
        - token: "acme-9f3c...key"
          tenant_id: "acme"
          expire_date: 1924905600
        - token: "globex-7a1b...key"
          tenant_id: "globex"

A request bearing Acme's token is tagged with its tenant; the client IP is preserved...

{
  "message": "{\"msg\":\"user login\"}",
  "_vmetric": {
    "device": { "id": 6, "name": "saas_http", "type": "http" },
    "event": {
      "request": "198.51.100.20",
      "tenant_id": "acme"
    }
  }
}

HMAC

HTTP server with SHA-256 HMAC signature verification:

HTTP server with HMAC signature verification...

devices:
  - id: 4
    name: hmac_http
    type: http
    properties:
      port: 8080
      url: "/secure/logs"
      authentication:
        type: "hmac"
      hmac:
        type: "sha256"
        header: "X-Signature"
        key: "${HMAC_SECRET}"
        prefix: "sha256="

The same with GitHub's legacy X-Hub-Signature header, signed with HMAC-SHA1:

HTTP server verifying GitHub's SHA-1 webhook signature...

devices:
  - id: 7
    name: github_http
    type: http
    properties:
      port: 8080
      url: "/github/webhook"
      authentication:
        type: "hmac"
      hmac:
        type: "sha1"
        header: "X-Hub-Signature"
        key: "${GITHUB_WEBHOOK_SECRET}"
        prefix: "sha1="

warning

When using HMAC authentication, ensure that the client calculates the signature using the same algorithm and key.

Secure

HTTPS server with TLS and basic authentication...

devices:
  - id: 5
    name: secure_http
    type: http
    properties:
      port: 8443
      url: "/api/ingest"
      tls:
        status: true
        cert_name: "server.crt"
        key_name: "server.key"
      authentication:
        type: "basic"
        username: "ingest_user"
        password: "${INGEST_PASSWORD}"
      response:
        code: 201
        body: '{"status":"created"}'
        content_type: "application/json"

warning

For production deployments, always use TLS encryption when authentication is enabled to protect credentials and tokens.

Synopsis​

Schema​

Configuration​

Device​

Protocol​

Response​

Authentication​

Multi-Tenancy​

TLS​

Advanced Configuration​

Performance​

Examples​

Basic​

Authentication​

API Keys​

Multi-Tenant Bearer Tokens​

HMAC​

Secure​

Synopsis

Schema

Configuration

Device

Protocol

Response

Authentication

Multi-Tenancy

TLS

Advanced Configuration

Performance

Examples

Basic

Authentication

API Keys

Multi-Tenant Bearer Tokens

HMAC

Secure