Goss - Quick and Easy server validation

**

Goss in 45 seconds

Note: For testing containers see the dgoss wrapper. Also, user submitted wrapper scripts for Kubernetes kgoss and Docker Compose dcgoss.

Note: For some Docker/Kubernetes healthcheck, health endpoint, and container ordering examples, see my blog post.

Introduction

What is Goss?

Goss is a YAML based serverspec alternative tool for validating a server's configuration. It eases the process of writing tests by allowing the user to generate tests from the current system state. Once the test suite is written they can be executed, waited-on, or served as a health endpoint.

Why use Goss?

• Goss is EASY! - Goss in 45 seconds
• Goss is FAST! - small-medium test suites are near instantaneous, see benchmarks
• Goss is SMALL! - <10MB single self-contained binary

Installation

Note: For macOS and Windows, see: platform-feature-parity.

This will install goss and dgoss.

Note: Using curl | sh is not recommended for production systems, use manual installation below.

# Install latest version to /usr/local/bin
curl -fsSL https://goss.rocks/install | sh

# Install v0.4.8 version to ~/bin
curl -fsSL https://goss.rocks/install | GOSS_VER=v0.4.8 GOSS_DST=~/bin sh

Manual installation

Latest

curl -L https://github.com/goss-org/goss/releases/latest/download/goss-linux-amd64 -o /usr/local/bin/goss
chmod +rx /usr/local/bin/goss

curl -L https://github.com/goss-org/goss/releases/latest/download/dgoss -o /usr/local/bin/dgoss
# Alternatively, using the latest master
# curl -L https://raw.githubusercontent.com/goss-org/goss/master/extras/dgoss/dgoss -o /usr/local/bin/dgoss
chmod +rx /usr/local/bin/dgoss

Specific Version

# See https://github.com/goss-org/goss/releases for release versions
VERSION=v0.4.8
curl -L "https://github.com/goss-org/goss/releases/download/${VERSION}/goss-linux-amd64" -o /usr/local/bin/goss
chmod +rx /usr/local/bin/goss

# (optional) dgoss docker wrapper (use 'master' for latest version)
VERSION=v0.4.8
curl -L "https://github.com/goss-org/goss/releases/download/${VERSION}/dgoss" -o /usr/local/bin/dgoss
chmod +rx /usr/local/bin/dgoss

Build it yourself

make build

Alternatively, you can build it with goreleaser. To build a binary, use gorelease build, and to only build for the same OS and architecture as the machine you're building on, include the --single-target flag. The --clean flag will clean up any existing builds, and --snapshot will allow you to build against something other than a tag.

Here's an example:

$ goreleaser build --clean --single-target --snapshot
  • skipping validate...
  • cleaning distribution directory
  • loading environment variables
  • getting and validating git state
    • ignoring errors because this is a snapshot     error=git doesn't contain any tags - either add a tag or use --snapshot
    • using tags                                     previous=<unknown> current=v0.0.0
    • pipe skipped or partially skipped              reason=disabled during snapshot mode
  • parsing tag
  • setting defaults
  • partial
  • snapshotting
    • building snapshot...                           version=0.0.1-next
  • running before hooks
    • running                                        hook=go mod tidy
  • ensuring distribution directory
  • setting up metadata
  • writing release metadata
  • loading go mod information
  • build prerequisites
  • building binaries
    • partial build                                  match=target=linux_arm64_v8.0
    • building                                       paths=cmd/goss binaries=goss target=linux_arm64_v8.0
      • took: 31s
  • writing artifacts metadata
  • build succeeded after 31s
  • thanks for using GoReleaser!
$ tree dist
dist
├── artifacts.json
├── binaries_linux_arm64_v8.0
│   └── goss                            <- your binary
├── config.yaml
└── metadata.json

2 directories, 4 files

Full Documentation

Full Documentation

Using the container image

Using the Goss container image

Quick start

Writing a simple sshd test

An initial set of tests can be derived from the system state by using the add or autoadd commands.

Let's write a simple sshd test using autoadd.

# Running it as root will allow it to also detect ports
$ sudo goss autoadd sshd

Generated goss.yaml:

port:
  tcp:22:
    listening: true
    ip:
    - 0.0.0.0
  tcp6:22:
    listening: true
    ip:
    - '::'
service:
  sshd:
    enabled: true
    running: true
user:
  sshd:
    exists: true
    uid: 74
    gid: 74
    groups:
    - sshd
    home: /var/empty/sshd
    shell: /sbin/nologin
group:
  sshd:
    exists: true
    gid: 74
process:
  sshd:
    running: true

Now that we have a test suite, we can:

• Run it once

$ goss validate
...............

Total Duration: 0.021s # <- yeah, it's that fast..
Count: 15, Failed: 0

• Edit it to use templates, and run with a vars file

goss --vars vars.yaml validate

• keep running it until the system enters a valid state or we timeout

goss validate --retry-timeout 30s --sleep 1s

• serve the tests as a health endpoint

$ goss serve &
$ curl localhost:8080/healthz

# JSON endpoint
$ goss serve --format json &
$ curl localhost:8080/healthz

# rspecish response via content negotiation
$ goss serve --format json &
$ curl -H "Accept: application/vnd.goss-rspecish" localhost:8080/healthz

Manually editing Goss files

Goss files can be manually edited to improve readability and expressiveness of tests.

A Json draft 7 schema available at https://goss.rocks/schema.yaml makes it easier to edit simple goss.yaml files in IDEs, providing usual coding assistance such as inline documentation, completion and static analysis. See #793 for screenshots.

For example, to configure the Json schema in JetBrains intellij IDEA, follow documented instructions, with arguments such as:

• schema url=https://goss.rocks/schema.yaml
• schema version=Json schema version 7
• file path pattern=*/goss.yaml

In addition, Goss files can also be further manually edited (without yet full json support) to use:

• Patterns
• Advanced Matchers
• Templates
• title and meta (arbitrary data) attributes are persisted when adding other resources with goss add

Some examples:

user:
  sshd:
    title: UID must be between 50-100, GID doesn't matter. home is flexible
    meta:
      desc: Ensure sshd is enabled and running since it's needed for system management
      sev: 5
    exists: true
    uid:
      # Validate that UID is between 50 and 100
      and:
        gt: 50
        lt: 100
    home:
      # Home can be any of the following
      or:
      - /var/empty/sshd
      - /var/run/sshd

package:
  kernel:
    installed: true
    versions:
      # Must have 3 kernels and none of them can be 4.4.0
      and:
      - have-len: 3
      - not:
          contain-element: 4.4.0

  # Loaded from --vars YAML/JSON file
  {{.Vars.package}}:
    installed: true

{{if eq .Env.OS "centos"}}
  # This test is only when $OS environment variable is set to "centos"
  libselinux:
    installed: true
{{end}}

Goss.yaml files with templates can still be validated through the Json schema after being rendered using the goss render command. See example below

$ cd docs
$ goss --vars ./vars.yaml render > rendered_goss.yaml
# proceed with json schema validation of rendered_goss.yaml in your favorite IDE
# or in one of the Json schema validator listed in https://json-schema.org/implementations.html
# The following example is for a Linux AMD64 host
$ curl -LO https://github.com/neilpa/yajsv/releases/download/v1.4.1/yajsv.linux.amd64
$ chmod a+x yajsv.linux.amd64
$ sudo mv yajsv.linux.amd64 /usr/sbin/yajsv

$ yajsv -s goss-json-schema.yaml rendered_goss.yaml

rendered_goss.yaml: fail: process.chrome: skip is required
rendered_goss.yaml: fail: service.sshd: skip is required
1 of 1 failed validation
rendered_goss.yaml: fail: process.chrome: skip is required
rendered_goss.yaml: fail: service.sshd: skip is required

JSON Schema maintains a table of validators.

Supported resources

• package - add new package
• file - add new file
• addr - add new remote address:port - ex: google.com:80
• port - add new listening [protocol]:port - ex: 80 or udp:123
• service - add new service
• user - add new user
• group - add new group
• command - add new command
• dns - add new dns
• process - add new process name
• kernel-param - add new kernel-param
• mount - add new mount
• interface - add new network interface
• http - add new network http url with proxy support
• goss - add new goss file, it will be imported from this one
• matching - test for matches in supplied content

Supported output formats

• rspecish - (default) Similar to rspec output
• documentation - Verbose test results
• json - JSON, detailed test result
• tap - TAP style
• junit - JUnit style
• nagios - Nagios/Sensu compatible output /w exit code 2 for failures.
• prometheus - Prometheus compatible output.
• silent - No output. Avoids exposing system information (e.g. when serving tests as a healthcheck endpoint).

Community Contributions

• goss-ansible - Ansible module for Goss.
• degoss - Ansible role for installing, running, and removing Goss in a single go.
• ansible-goss-install - Ansible role for installing Goss (option for install as user or root)
• kitchen-goss - A test-kitchen verifier plugin for Goss.
• goss-fpm-files - Might be useful for building goss system packages.
• packer-provisioner-goss - A packer plugin to run Goss as a provision step.
• gossboss - Collect and view aggregated Goss test results from multiple remote Goss servers.

Limitations

goss works well on Linux, but support on Windows & macOS is alpha. See platform-feature-parity.

The following tests have limitations.

Package:

• rpm
• deb
• Alpine apk
• pacman

Service:

• systemd
• sysV init
• OpenRC init
• Upstart