Hub configuration

The Hub supports additional configuration via a YAML file that can be mounted into the container at runtime.

This enables configuration of:

  1. Audit Log destinations

Here is an example configuration file:

---
# example hub config file
auditLog:
  # define a list of sinks that will receive audit log events
  sinks:
    # sinks are of type `file` or `udp`
    # - `file` sinks require a `path`
    # - `udp` sinks require a `host` and a `port`
    #
    # All other attributes are optional
    #
    - type: file

      # `path` is required for `file` type sinks
      path: /tmp/hazy/hub.log

      # currently we only support the `json` format
      #
      format: json

      # level should be one of "trace", "debug", "info", "notice", "warn", "error", "critical"
      # only events greater than the given severity will be sent to this sink
      #
      level: trace

      # metadata should be a map, it's values are merged into all log lines
      #
      metadata:
        env: development

      # the file permissions of the log file - the hub application will run as
      # some `nobody` (or equivalent) user so it's advisable to set group- and
      # world- read permissions
      #
      # mode: 0644
      #
      #

    - type: udp
      # udp sinks require a `host` and `port` to be set. The `host` can be an IP
      # address or hostname.
      host: localhost
      port: 11367
      # level: trace
      # format: json
      # metadata: {}

The configuration file should be mounted into the Hub container at /etc/hazy/hub.yaml (see the example run commands in Hub Installation).

If there are any errors in this configuration file, such as missing required values, then the Hub will provide an error message describing the problem and exit.

Audit Log Destinations

The Hub allows for multiple log destinations (or sinks) to be configured, each with separate logging levels and custom additional metadata.

For detailed information about the actual messages sent to the sinks, please see the audit log documentation.

Each sink can be of either file or udp type. File and UDP sinks have a set of shared type-specific options

Shared Options

  • format. Default json. The format that the log messages are written in. Currently json is the only supported format.

  • level. Default info. This specifies the minimum log level that will get sent to this sink. See the guide to audit logging for the list of supported event severity levels.

  • metadata. Default {}. A map of additional information to embed into every event. This can be useful when aggregating logs.

Additionally file and UDP sinks have a number of type-specific configuration parameters.

File Sinks

  • path. Required The absolute path to the log file the Hub should write to. This should be relative to the container filesystem, so you should be careful to use the path as-mounted in the Hub container, not the path on the host machine.

    An example of mounting a log directory into a Hub container

    docker run 
      # mount the hosts log directory into the container under /var/log/audit
      -v /var/log/hazy:/var/log/audit
      # ... standard arguments
      hazy/hub:release
    

    And the corresponding hub.yaml sink entries:

    - type: file
      level: trace
      path: /var/log/audit/hub-trace.log
    
    - type: file
      level: warning
      path: /var/log/audit/hub-warning.log
    
  • mode. Default 0644. Set permissions of the generated log file. These are in standard Unix octal format. The Hub won't modify the permissions of a pre-existing file.

For security reasons, the Hub application runs as an unprivileged user within the container.

It's important to ensure that the Hub user has the necessary permissions to write to the host path that holds the log files. This may require granting very open permissions to the host's log directory in order for the Hub application to write to the file (e.g. chmod 0777 /var/log/hazy in the above example).

Alternatively you can pre-create the log file using the host's root account and then assign very loose permissions to the file itself , not the containing directory (e.g. touch /var/log/hazy/hub-trace.log && chmod 0777 /var/log/hazy/hub-trace.log in the above example).

UDP Sinks

UDP sinks allow for the collection of logs on remote hosts. Log messages will be sent in JSON format as single UDP packets to the configured host:port.

  • host. Required. The hostname or IP address of the destination server.

  • port. Required. The port of the destination service

Example configuration

---
auditLog:
  sinks:
    - type: udp
      host: logs.internal.contoso.com
      port: 11367