sumo

Install and configure the Sumo Logic collector on Linux and Windows using local software distribution. Providing more control over lifecycle.

Table of Contents

• Description
• Setup
  • Setup Requirements
    • Windows
    • Linux
  • Beginning with sumo
• Usage
• Limitations
• Development

Description

There are currently a few SumoLogic modules already. Most notably https://forge.puppet.com/pjorg/sumo and https://github.com/SumoLogic/sumologic-collector-puppet-module. The problem with the former is that it does not support Windows or many of the options for the user.properties file. The problem with the latter is that it assumes every node can directly connect to the internet for curl (some firewalls only allow Sumo profile traffic) and it doesn't allow you to upgrade or control the package versions. So this module takes the approach of the former, but the detail from the second.

This module assumes an existing package management solution is in place (YUM for RHEL/SLES and Chocolatey for Windows). It takes the following platform approach:

• Windows - install pkg via chocolatey with the site customisation being driven during pkg install. Upgradeable via Chocolatey.
• Linux - install RPM, configure, then start sumo. Upgradeable via RPM.

Setup

Setup Requirements

Windows

Assumes a functional Chocolatey environment and that the Sumo Logic Collector installer for Windows has been correctly imported into Chocolatey.

Setup the Chocolatey package so that it installs the exe with the following command line options:

-console -q -varfile 'C:\windows\temp\sumoVarFile.txt'

Linux

Download the Sumo Logic Collector package for your respective flavours and import into your repos.

Beginning with sumo

Put the relevant configuration information into Hiera:

sumo::accessid: lkskj98983hjhj
sumo::accesskey: jlkdlkaldkalkda984nb197jdnkjsomjsdkjiocjJAOSALDJWBDahsikldjkja78
sumo::sumo_package_ver: 19.253-26
sumo::sources_path: "/tmp/sumo-%{osfamily}.json"

Call in the sumo class in your required scope:

  class { 'sumo': }

Usage

Expanding on the previous section, all the user properties can be specified in hiera. Here are the defaults that can be overridden by site requirements:

---
sumo::accessid:                null
sumo::accesskey:               null
sumo::category:                null
sumo::clobber:                 true
sumo::collector_name:          "%{::hostname}"
sumo::collector_secure_files:  true
sumo::collector_url:           https://collectors.sumologic.com
sumo::description:             null
sumo::enable_action_source:    false
sumo::enable_script_source:    false
sumo::disable_upgrade:         true
sumo::ephemeral:               false
sumo::hostname:                "%{::hostname}"
sumo::proxy_host:              null
sumo::proxy_ntlmdomain:        null
sumo::proxy_password:          null
sumo::proxy_port:              null
sumo::proxy_user:              null
sumo::skip_access_key_removal: false
sumo::skip_registration:       false
sumo::local_config_mgmt:       false
sumo::sources_path:            null
sumo::sync_sources_path:       null
sumo::target_cpu:              null
sumo::time_zone:               null
sumo::token:                   null
sumo::runas_username:          null
sumo::win_run_as_password:     null
sumo::install_properties_path: null
sumo::user_properties_path:    /opt/SumoCollector/config/user.properties
sumo::package:
  name:    SumoCollector
  version: latest
sumo::service:
  name:    collector
  running: true
  enabled: true

Here are the Windows overrides:

sumo::service:
  name: sumo-collector
sumo::install_properties_path: 'C:\windows\temp\sumoVarFile.txt'
sumo::user_properties_path:    'C:\Program Files\Sumo Logic Collector\config\user.properties'

If you want to install globally except on a few test systems, then you can specify the following Hiera in the scope of the test systems so that it will not be installed or configured on them:

sumo::install: false

Please refer to Sumo documentation for an explanation of each setting: https://help.sumologic.com/03Send-Data/Installed-Collectors/05Reference-Information-for-Collector-Installation/06user.properties. (Bear in mind, some of the properties have been slightly modified, but it should be reasonably clear how they align).

See the Reference.md file for more detailed information.

Limitations

• Nothing implemented for UNIX in this version.
• Assumes chocolatey is the Windows package manager.
• Debian/Ubuntu probably works, but is untested.

Development

If you would like to contribute to this module, please submit a PR on github. Thanks.

Reference

Table of Contents

Classes

• sumo: Configures the Sumo Collector on Windows and Linux

Classes

sumo

Configures the Sumo Collector on Windows and Linux

Examples

Basic usage

class { 'sumo': }

Set the following in the relevant hiera scope:

sumo::accessid: lkskj98983hjhj
sumo::accesskey: jlkdlkaldkalkda984nb197jdnkjsomjsdkjiocjJAOSALDJWBDahsikldjkja78
sumo::sumo_package_ver: 19.253-26
sumo::sources_path: "/tmp/sumo-%{osfamily}.json"

Parameters

The following parameters are available in the sumo class.

install

Data type: Boolean

Whether to install and configure the Sumo Logic collector. It defaults to true, but is implemented so that the collector can be configured globally, but not installed on nodes in certain Hiera scopes.

accessid

Data type: String

The Sumo Logic collector access ID

accesskey

Data type: String

The Sumo Logic collector access Key

category

Data type: Optional[String]

Source category to use when a source does not specify a category.

clobber

Data type: Boolean

When true, if there is any existing collector with the same name, that collector will be deleted (clobbered).

collector_name

Data type: String

Sets the name of collector used on Sumo Logic. The name can be a maximum of 128 characters.

collector_secure_files

Data type: Boolean

By default, new Collector installations will use Enhanced File System Security. To disable this feature during installation, set this to false.

collector_url

Data type: String

Sets the URL used to register collector for data collection API.

description

Data type: Optional[String]

Description for the collector to appear in Sumo Logic.

enable_action_source

Data type: Boolean

Script Action Sources are disabled by default. You can enable them by setting this parameter to true.

enable_script_source

Data type: Boolean

Script Sources are disabled by default. You can enable them by setting this parameter to true.

disable_upgrade

Data type: Boolean

If true, the collector rejects upgrade requests from Sumo.

ephemeral

Data type: Boolean

When true, the collector will be deleted after 12 hours of inactivity.

hostname

Data type: String

The host name of the machine on which the collector is running.

local_config_mgmt

Data type: Boolean

Needs yo be false when using ''sources_path'' and true when using ''sync_sources_path''.

proxy_host

Data type: Optional[String]

Sets proxy host when a proxy server is used.

proxy_ntlmdomain

Data type: Optional[String]

Sets proxy NTLM domain when a proxy server is used with NTLM authentication.

proxy_password

Data type: Optional[String]

Sets proxy password when a proxy server is used with authentication.

proxy_port

Data type: Optional[String]

Sets proxy port when a proxy server is used.

proxy_user

Data type: Optional[String]

Sets proxy user when a proxy server is used with authentication.

skip_access_key_removal

Data type: Boolean

If true, it will skip the access key removal from the user.properties file.

skip_registration

Data type: Boolean

Collectors normally register with Sumo Logic during the installation process, but setting this flag to true will skip registration. This way, the collector is installed as a service that will start and register automatically when next booted or started.

sources_path

Data type: Optional[String]

Specifies a single UTF-8 encoded JSON file, or a folder containing UTF-8 encoded JSON files, that defines the Sources to configure upon Collector registration. The contents of the file or files is read upon Collector registration only, it is not synchronized with the Collector's configuration on an on-going basis.

sync_sources_path

Data type: Optional[String]

Specifies either a single UTF-8 encoded JSON file, or a folder containing UTF-8 encoded JSON files, that define the Sources to configure upon Collector registration. The Source definitions will be continuously monitored and synchronized with the Collector's configuration.

target_cpu

Data type: Optional[Integer]

You can choose to set a CPU target to limit the amount of CPU processing a collector uses. The value must be expressed as a whole number percentage string, e.g. 20.

time_zone

Data type: Optional[String]

The time zone to use when it is not extracted from the log timestamp.

token

Data type: Optional[String]

Sets the Setup Wizard Token, a one-time use token, available for one hour after it is generated, then it expires. This token authenticates the user. It is designed to be used for only one Collector. The token cannot be used with the API, and it cannot be disabled.

runas_username

Data type: Optional[String]

When set, the Collector will run as the specified user (Windows and Linux). For Windows, the user account needs Log on as a Service permission.

win_run_as_password

Data type: Optional[String]

(Windows only) When set in conjunction with runas_username, the Collector will run as the specified user with the specified password.

user_properties_path

Data type: String

Set the absolute path of the user.properties file. It default to the location in the default install location.

install_properties_path

Data type: Optional[String]

Set this to the location specified in the Chocolatey configuration. Default is 'C:\windows\temp\sumoVarFile.txt'.

package

Data type: Struct[{name => String, version => String}]

Set the name and version of the package to install

service

Data type: Struct[{name => String, running => Boolean, enabled => Boolean}]

Set the name and state of the collector service

Changelog

All notable changes to this project will be documented in this file.

Release 0.1.0

Features

Bugfixes

Known Issues