sysfact

README

sysfact

A utility for collecting and formatting system information.

Overview

The sysfact utility provides a simple, structured mechanism for collecting and formatting pieces of information about Linux, BSD, macOS, and other operating systems. It achieves this using collection scripts, which run in parallel when sysfact is invoked to gather details. Collection scripts can be written in any language, as they are called via a shell process-- they only need to be executable to run. Scripts emit details, one per line, to standard output with a simple format: metricname:type:value\n

Installation

Binaries

Soon. Soon...

From Source

go get -u github.com/ghetzel/sysfact/cmd/sysfact

Formatting

For example, here is a some output that would be usable by sysfact:

demo.things.enabled:bool:true
demo.items.0.name:str:Item 1: Things
demo.items.0.count:int:42
demo.items.0.factor:float:3.14
demo.items.1.name:str:Item 2: Stuff
demo.items.1.count:int:99
demo.items.1.factor:float:2.178
demo.items.1.active:bool:true

This is what the above would look like using the "json" format option:

{
	"demo": {
		"items": [
			{
				"count": 42,
				"factor": 3.14,
				"name": "Item 1: Things"
			},
			{
				"active": true,
				"count": 99,
				"factor": 2.178,
				"name": "Item 2: Stuff"
			}
		],
		"things": {
			"enabled": true
		}
	}
}

Output can be formatted into JSON, YAML, as a flat list of "key=value" items, or in several popular timeseries string formats; like InfluxDB's Line Protocol, OpenTSDB/KairosDB, and Graphite.

Output

Finally, the results of formatting the collected data can be output, either via standard output (the default), or using the built-in HTTP client. You can specify a URL, HTTP method, request headers, query string parameters (as command line flags), and timeouts. This provides a flexible and powerful mechanism for using sysfact as a component in monitoring, inventory collection, and other data collection systems.

File Management & Templating

Sysfact also has a built-in mechanism for copying directory trees from one location to another, while also allowing for individual files and filenames to make use of data gathered by a Sysfact report. This is a simple but powerful mechanism for providing very bare-bones management of files on a system.

For example, lets take the following directory tree:

~/.config/sysfact/apply/
├── any
│   └── any
│       ├── .bashrc
│       ├── .config
│       │   └── gtk-3.0
│       │       └── settings.ini
│       └── .mpd
│           └── mpd.conf
└── ubuntu
    └── x86_64
        ├── @.bashrc
        ├── .config
        │   └── systemd
        │       └── user
        │           ├── default.target.wants
        │           │   └── sysfact-apply.service -> ../sysfact-apply.service
        │           ├── sysfact-apply.service
        │           ├── sysfact-apply.timer
        │           └── timer.target.wants
        │               └── sysfact-apply.timer -> ../sysfact-apply.timer
        └── @.sysfact-[[os.distribution]]-[[os.version]].json

By default, these files and directories represent files that you want to copy to their respective locations relative to your home directory (~). When you run sysfact apply, each file in this tree will be visited and copied into your home directory. Intermediate directories will be created, and the files will be placed in them.

Using Templates to Generate Files

Note the @ symbol in the filename @.bashrc. This tells Sysfact that the file should be treated as a template. The template engine will pass the complete Sysfact Report as input, along with any additional values you provide, and generate a text file as output with the values interopolated in. The resulting filename will have the leading @ omitted. In this example, the rendered template will be placed at ~/.bashrc.

Templates are standard Golang text/template files, with additional functions provided by the Diecast Standard Function Library.

Environment-Specific Overrides

Note that there are several roots in play here. The bulk of the files reside in ./any/any/, but some of them are in the ./ubuntu/x86_64/ directory. Sysfact allows you to specify files and directories that should only be copied to the destination directory under specific OS, Distribution, Archicture, or OS Family combinations. Below is a list of the default order used to determine which files are copied over. You may also provide additional search patterns that will be appended to this default list. Patterns may use any value that appears in the sysfact report.

- `<srcdir>/any/any/`
- `<srcdir>/any/${arch}/`
- `<srcdir>/${os.platform}/any/`
- `<srcdir>/${os.platform}/${arch}/`
- `<srcdir>/${os.family}/any/`
- `<srcdir>/${os.family}/${arch}/`
- `<srcdir>/${os.distribution}/any/`
- `<srcdir>/${os.distribution}/${arch}/`
- `<srcdir>/${os.distribution}-${os.version}/any/`
- `<srcdir>/${os.distribution}-${os.version}/${arch}/`
- `<srcdir>/${domain}/`
- `<srcdir>/${hostname}/`
- `<srcdir>/${hostname}.${domain}/`
- `<srcdir>/${fqdn}/`
- `<srcdir>/${uuid}/`

It is entirely possible to have the same filenames reside in multiple roots, with more-specific ones overwriting less specific versions. For example, the file ./any/any/.bashrc would be copied to ~/.bashrc first. If sysfact is being run on a 64-bit Ubuntu installation (any version), the ./ubuntu/x86_64/@.bashrc file will be read, rendered as a template (because of the leading @), and overwrite the ~/.bashrc file that was copied from before. This simple but powerful mechanism allows for very flexible file structures to be created that adapt to the needs of the system being configured.

Templated Filenames

File and directory names themselves can also be templated by specifying values surrounded by double square brackets ([[ and ]]). The values inside the square brackets work the same way as the patterns mentioned above, including fallback values and %-formatting directives.

Take a look at the source file ./ubuntu/x86_64/@.sysfact-[[os.distribution]]-[[os.version]].json. There's a fair bit going on here:

• This file will only be created on 64-bit Ubuntu hosts
• It will be treated as a template.
• The filename itself will also be expanded. If run on a 64-bit Ubuntu 18.04 machine, the resulting file will be placed at ~/.sysfact-ubuntu-18.04.json.

Default Paths

When sysfact is run as a normal (i.e.: non-root) user, the default source and destination paths are:

• srcdir: ~/.config/sysfact/apply/
• destdir: ~/

When run as root, sysfact defaults to using:

• srcdir: /etc/sysfact/apply/
• destdir: /

This allows sysfact to be used by both regular users to manage their home directories, or by administrators to configure entire systems.

Documentation

Index

• Constants
• Variables
• func Render(basedir string, options *RenderOptions) error
• func RenderString(data map[string]interface{}, template string) (string, error)
• func Report(paths ...string) (map[string]interface{}, error)
• type InfluxdbPayload
  • func (self InfluxdbPayload) Generate(series TupleSet, tags map[string]interface{}, now *time.Time) (string, error)
• type RenderOptions
  • func (self *RenderOptions) Enforce(path string) error
  • func (self *RenderOptions) ModeFor(info os.FileInfo) os.FileMode
• type Reporter
  • func NewReporter(paths ...string) *Reporter
  • func (self *Reporter) GetReportValues(fields []string, skipFields []string) (map[string]interface{}, error)
  • func (self *Reporter) Report() (map[string]interface{}, error)
• type ReporterKeyFormat
• type Trigger
  • func (self Trigger) Do(action string, path string, data map[string]interface{}, logger logFunc) error
  • func (self Trigger) Should(action string, path string) bool
• type Tuple
• type TupleSet
  • func (self TupleSet) Len() int
  • func (self TupleSet) Less(i, j int) bool
  • func (self TupleSet) Remove(i int)
  • func (self TupleSet) Swap(i, j int)
  • func (self TupleSet) ToMap(flat bool) map[string]interface{}

Constants

const Version = `0.8.2`

Variables

var InfluxdbTagValueCharCompress = regexp.MustCompile(`[\s,]+`)

var InfluxdbTagValueCharFilter = regexp.MustCompile(`\s{2,}`)

var OptionsFile = `sysfact.yaml`

var RenderAsTemplatePrefix = `@`

var RenderPatterns = []string{
	`any/any`,
	`any/${arch}`,
	`${os.platform}/any`,
	`${os.platform}/${arch}`,
	`${os.family}/any`,
	`${os.family}/${arch}`,
	`${os.distribution}/any`,
	`${os.distribution}/${arch}`,
	`${os.distribution}-${os.version}/any`,
	`${os.distribution}-${os.version}/${arch}`,
	`${domain}`,
	`${hostname}`,
	`${hostname}.${domain}`,
	`${fqdn}`,
	`${uuid}`,
}

Functions

func Render

func Render(basedir string, options *RenderOptions) error

func RenderString

func RenderString(data map[string]interface{}, template string) (string, error)

Render the given template string using the given data.

func Report

func Report(paths ...string) (map[string]interface{}, error)

Generate a system report using the default settings.

Types

type InfluxdbPayload

type InfluxdbPayload []string

func (InfluxdbPayload) Generate

func (self InfluxdbPayload) Generate(series TupleSet, tags map[string]interface{}, now *time.Time) (string, error)

type RenderOptions

type RenderOptions struct {
	SourceDir          string    `yaml:"srcdir"`
	DestDir            string    `yaml:"destdir"  default:"~"`
	DefaultDirMode     int       `yaml:"dirmode"  default:"493"`
	DefaultFileMode    int       `yaml:"filemode" default:"420"`
	Owner              string    `yaml:"owner"`
	Group              string    `yaml:"group"`
	DryRun             bool      `yaml:"dryrun"`
	FollowSymlinks     bool      `yaml:"follow_symlinks"`
	AdditionalPatterns []string  `yaml:"patterns"`
	Triggers           []Trigger `yaml:"triggers"`
	// contains filtered or unexported fields
}

func (*RenderOptions) Enforce

func (self *RenderOptions) Enforce(path string) error

func (*RenderOptions) ModeFor

func (self *RenderOptions) ModeFor(info os.FileInfo) os.FileMode

type Reporter

type Reporter struct {
	Plugins     []plugins.Plugin
	FieldPrefix string
	KeyFormat   ReporterKeyFormat
}

func NewReporter

func NewReporter(paths ...string) *Reporter

Create a new Reporter instance that can be configured.

func (*Reporter) GetReportValues

func (self *Reporter) GetReportValues(fields []string, skipFields []string) (map[string]interface{}, error)

Generates a report and retrieves the values of the given fields.

func (*Reporter) Report

func (self *Reporter) Report() (map[string]interface{}, error)

Generate and return the full report from all discovered plugins.

type ReporterKeyFormat

type ReporterKeyFormat int

const (
	FormatUnderscore ReporterKeyFormat = iota
	FormatPascalize
	FormatCamelize
)

type Trigger

type Trigger struct {
	On      string `yaml:"on"`
	Command string `yaml:"command"`
}

func (Trigger) Do

func (self Trigger) Do(action string, path string, data map[string]interface{}, logger logFunc) error

func (Trigger) Should

func (self Trigger) Should(action string, path string) bool

type Tuple

type Tuple struct {
	Key           string
	Value         interface{}
	NormalizedKey string
	Tags          map[string]interface{}
}

type TupleSet

type TupleSet []Tuple

func (TupleSet) Len

func (self TupleSet) Len() int

func (TupleSet) Less

func (self TupleSet) Less(i, j int) bool

func (TupleSet) Remove

func (self TupleSet) Remove(i int)

func (TupleSet) Swap

func (self TupleSet) Swap(i, j int)

func (TupleSet) ToMap

func (self TupleSet) ToMap(flat bool) map[string]interface{}