goss

by aelsabbahy

aelsabbahy / goss

Quick and Easy server testing/validation

4.1K Stars 359 Forks Last release: 4 months ago (v0.3.13) Apache License 2.0 430 Commits 55 Releases

Available items

No Items, yet!

The developer of this repository has not created any items for sale yet. Need a bug fixed? Help with integration? A different license? Create a request here:

Goss - Quick and Easy server validation

Build Status Github All Releases ** Blog

Goss in 45 seconds

asciicast

Note: For an even faster way of doing this, see: autoadd

Note: For testing docker 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 here.

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.3.6 version to ~/bin

curl -fsSL https://goss.rocks/install | GOSS_VER=v0.3.6 GOSS_DST=~/bin sh

Manual installation

Latest

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

curl -L https://github.com/aelsabbahy/goss/releases/latest/download/dgoss -o /usr/local/bin/dgoss

Alternatively, using the latest master

curl -L https://raw.githubusercontent.com/aelsabbahy/goss/master/extras/dgoss/dgoss -o /usr/local/bin/dgoss

chmod +rx /usr/local/bin/dgoss

Specific Version

# See https://github.com/aelsabbahy/goss/releases for release versions
VERSION=v0.3.10
curl -L "https://github.com/aelsabbahy/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.3.10 curl -L "https://github.com/aelsabbahy/goss/releases/download/${VERSION}/dgoss" -o /usr/local/bin/dgoss chmod +rx /usr/local/bin/dgoss

Build it yourself

make build

Full Documentation

Documentation is available here: manual

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
:
$ cat 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 #

  • 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 use:

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}}

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
  • 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.
  • 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.
  • kitchen-goss - A test-kitchen verifier plugin for Goss.
  • goss-fpm-files - Might be useful for building goss system packages.
  • molecule - Automated testing for Ansible roles, with native Goss support.
  • packer-provisioner-goss - A packer plugin to run Goss as a provision step.

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

We use cookies. If you continue to browse the site, you agree to the use of cookies. For more information on our use of cookies please see our Privacy Policy.