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>
    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 (`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.

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`	Skip peer certificate verification. Use only for testing.

* = 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
`reuse`	N	`true`	Enable socket address reuse
`workers`	N	CPU count	Number of worker processes when reuse is enabled. Capped at the number of physical cores.

note

flush_interval and queue.interval are Director service-level settings configured in vmetric.yml and cannot be overridden per device.

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="

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