Skip to main content

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>
      min_version: <string>
      insecure_skip_verify: <boolean>
    authentication:
      type: <string>
      username: <string>
      password: <string>
    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​

FieldRequiredDefaultDescription
idYUnique identifier
nameYDevice name
descriptionN-Optional description
typeYMust be http
tagsN-Optional tags
pipelinesN-Optional pre-processor pipelines
statusNtrueEnable/disable the device

Protocol​

FieldRequiredDefaultDescription
protocolN"tcp"Transport protocol (typically tcp).
addressN"0.0.0.0"Listen address
portYListen port
urlN"/"URL path to listen on
content_typeN"application/json"Expected content type of incoming requests

Response​

FieldRequiredDefaultDescription
response.codeN200HTTP response status code
response.bodyN{"message":"success"}Response body content
response.content_typeN"application/json"Response content type

Authentication​

FieldRequiredDefaultDescription
authentication.typeN"none"Authentication type (basic, header, or hmac)
authentication.usernameY*Username for basic auth
authentication.passwordY*Password for basic auth
header.keyY*Header name for header auth
header.valueY*Header value for header auth
hmac.typeY*HMAC algorithm (sha256 or sha512)
hmac.headerY*Header name for HMAC signature
hmac.keyY*Secret key for HMAC calculation
hmac.prefixN-Optional prefix to strip from HMAC header value

* = Required when authentication.type is set to the corresponding method.

TLS​

FieldRequiredDefaultDescription
tls.statusNfalseEnable TLS encryption
tls.cert_nameY*TLS certificate. Accepts a file name (resolved relative to the service root directory) or inline PEM content (when the value starts with -----BEGIN).
tls.key_nameY*TLS private key. Same value semantics as tls.cert_name.
tls.min_versionN"1.2"Minimum TLS version ("1.0", "1.1", "1.2", "1.3")
tls.insecure_skip_verifyNfalseSkip peer certificate verification. Use only for testing.

* = Required when tls.status is true.

Advanced Configuration​

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

Performance​

FieldRequiredDefaultDescription
reuseNtrueEnable socket address reuse
workersNCPU countNumber 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}"

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.