Quick and Easy server testing/validation

License: Apache-2.0

Language: Go

Keywords: devops, devops-tools, docker, go, golang, goss, health-check, health-endpoint, infrastructure-as-code, linux, nagios, sensu, tap, tdd, tdd-utilities, testing, testing-tools

Goss - Quick and Easy server validation

Build Status Github All Releases ** Twitter Follow Blog

Goss in 45 seconds

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

Note: For some Docker use cases, see my blog post here and dockerhub repo



What is Goss?

Goss is a YAML based serverspec-like 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 suits are near instantaneous, see benchmarks
  • Goss is SMALL! - <10MB single self-contained binary


# Install latest version to /usr/local/bin
curl -fsSL | sh

# Install v0.2.4 version to ~/bin
curl -fsSL | GOSS_VER=v0.2.4 GOSS_DST=~/bin sh

Manual installation

# See for release versions
curl -L -o /usr/local/bin/goss
chmod +rx /usr/local/bin/goss

Full Documentation

Documentation is available here:

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
    listening: true
    listening: true
    - '::'
    enabled: true
    running: true
    exists: true
    uid: 74
    gid: 74
    - sshd
    home: /var/empty/sshd
    shell: /sbin/nologin
    exists: true
    gid: 74
    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

  • 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

Patterns, matchers and metadata

Goss files can be manually edited to match:

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

Some examples:

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

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

Supported resources

  • package - add new package
  • file - add new file
  • addr - add new remote address:port - ex:
  • 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

Supported output formats

  • rspecish (default) - Similar to rspec output
  • documentation - Verbose test results
  • JSON - Detailed test result
  • TAP
  • JUnit
  • nagios - Nagios/Sensu compatible output /w exit code 2 for failures.
  • nagios_verbose - nagios output with verbose failure output.

Community Contributions


Currently goss only runs on Linux.

The following tests have limitations.


  • rpm
  • deb
  • Alpine apk
  • pacman


  • systemd
  • sysV init
  • OpenRC init
  • Upstart

Project Statistics

Sourcerank 10
Repository Size 537 KB
Stars 3,439
Forks 289
Watchers 86
Open issues 164
Dependencies 26
Contributors 12
Tags 47
Last updated
Last pushed

Top Contributors See all

Ahmed Elsabbahy Michael Prokop Ryan Cox Langston Barrett BeHe Matt Carroll Robert Hall Guillaume Grossetie Tim Birkett Matt Robinson Adham Dariusz Dwornikowski

Packages Referencing this Repo
Quick and Easy server testing/validation
Latest release v0.3.5 - Published - 3.44K stars
Quick and Easy server testing/validation
Latest release v0.3.5 - Published - 3.44K stars
Quick and Easy server testing/validation
Latest release v0.3.5 - Published - 3.44K stars
Quick and Easy server testing/validation
Latest release v0.3.5 - Published - 3.44K stars
Quick and Easy server testing/validation
Latest release v0.3.5 - Published - 3.44K stars
Quick and Easy server testing/validation
Latest release v0.3.5 - Published - 3.44K stars

Recent Tags See all

v0.3.5 September 12, 2017
v0.3.4 July 21, 2017
v0.3.3 July 10, 2017
v0.3.2 April 23, 2017
v0.3.1 March 15, 2017
v0.3.0 March 06, 2017
v0.2.6 February 18, 2017
v0.2.5 December 10, 2016
v0.2.4 September 28, 2016
issue/147 September 13, 2016
v0.2.3 August 11, 2016
v0.2.2 August 04, 2016
v0.2.1 August 02, 2016
v0.2.0 August 02, 2016
v0.1.10 July 26, 2016

Interesting Forks See all

Quick and Easy server testing/validation
Go - Apache-2.0 - Last pushed - 2 stars
Quick and Easy server testing/validation
Go - Apache-2.0 - Updated - 1 stars - 1 forks
Quick and Easy server testing/validation
Go - Published - 1 stars

Something wrong with this page? Make a suggestion

Last synced: 2016-11-24 16:53:57 UTC

Login to resync this repository