Skip to main content

Quick Start: Devices

This chapter will help you get started with devices to ingest data with specific protocols, walking you through common scenarios.

note

For a general discussion, see our overview chapter.

Configuration Files​

The device configuration files reside in the devices directory under the config folder, and have a .yml extension:

├───config
│   ├───devices
│   │       syslog.yml
│   │
│   ├───routes
│   │       default.yml
│   │
│   └───targets
│           console.yml
│           file.yml

Director discovers these files by traversing the subdirectories recursively.

note

Each device type provides specific options detailed in its respective chapter.

You can organize your device files as you wish, regardless of the above folder tree. This can be done in two ways:

  • Using a standalone file:

    C:\Users\<user-name>\Documents\syslog.yml

  • Using a listener-based grouping:

    C:\<vm_root>\listeners\syslog.yml

Choose the one that best fits your needs.

Basic UDP Setup​

1. Create Configuration​

Create a text file with a .yml extension in your preferred location, and then open it with a text editor to enter the following:

- id: 1
  name: syslog_udp
  type: syslog
  properties:
    protocol: udp
    address: 0.0.0.0
    port: 514

This YAML code specifies that your device is a Syslog, and that you will use UDP as your listening protocol on port 514. You can enter any integer as your id value.

2. Test Configuration​

You can now test this configuration using either Director's cross-platform companion Generator or traditional tools available:

Using Generator

vmetric-generator -mode=syslog -address=127.0.0.1:514 -message="Test Message"

Secure TCP Setup​

We will now create a secure TLS configuration.

1. Prepare Certificates​

First we have to prepare the TLS certificates. This can be done using either Director or OpenSSL.

Using Director

vmetric-director -pfx2pem=./cert-file.pfx # Windows

This generates the key.pem and cert.pem files.

warning

Always use TLS encryption in production environments, especially over untrusted networks. Ensure proper file permissions are set on these files:

  • the private key file (key.pem) should be readable only by the Director process
  • the certificate file (cert.pem) can be world-readable

2. Place Certificates​

Now that we have created these files, we must copy them to our installation root directory:

Copy-Item cert.pem key.pem <vm_root>/

3. Create Secure Configuration​

We will now prepare a secure configuration by creating another .yml file named secure_syslog.yml:

- id: 2
  name: syslog_secure
  type: syslog
  properties:
    protocol: tcp
    address: 0.0.0.0
    port: 6514
    tls:
      status: true
      cert_name: cert.pem
      key_name: key.pem
    framing: octet
    max_connections: 1000
    timeout: 300
    batch_size: 5000
    queue:
      interval: 2

Note that we have specified the certificate files we have previously created.

4. Test Configuration​

Test the secure connection:

Write-Output "Test secure message" | openssl s_client -connect 127.0.0.1:6514

Monitoring​

Check Director's logs for success messages on launching and initialization, connection acceptance, and configuration validation.

tip

Worker counts, buffer sizes, and batch settings can be adjusted based on your volumes.

Optimizing​

For high-volume environments, add the following to your configuration:

  reuse: true
  workers: 4
  buffer_size: 32768
  flush_interval: 5

These parameters will all have an impact on performance.