Goss – Quick and Easy server validation

Build Status Go Report Card Test Coverage

Goss in 45 seconds

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

Note: For testing docker containers see the dgoss wrapper

Note: For some Docker/Kubernetes healthcheck, health endpoint, and container ordering examples, see the blog post from @aelsabbahy here.



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

Why a fork?

I forked this project because the original repository isn’t under active development anymore. Due to the reason we use it heavily in production I started this fork.


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://raw.githubusercontent.com/SimonBaeumer/goss/add-coverage/install.sh | sh

# Install v0.4.0 version to ~/bin
curl -fsSL https://raw.githubusercontent.com/SimonBaeumer/goss/add-coverage/install.sh | GOSS_VER=v0.4.0 GOSS_DST=~/bin sh

Manual installation

# See https://github.com/aelsabbahy/goss/releases for release versions
curl -L https://github.com/SimonBaeumer/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)
curl -L https://raw.githubusercontent.com/SimonBaeumer/goss/_VERSION_/extras/dgoss/dgoss -o /usr/local/bin/dgoss
chmod +rx /usr/local/bin/dgoss

Build it yourself

# Enable git-hooks for development environments
make init
# Build the source
make build

Full Documentation

Documentation is available here: https://github.com/SimonBaeumer/goss/blob/master/docs/manual.md

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

Manually editing Goss files

Goss files can be manually edited to use:

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

  # Loaded from --vars YAML/JSON file
    installed: true

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

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 – Detailed test result
  • TAP
  • JUnit
  • 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.


Currently goss only runs on Linux.

The following tests have limitations.


  • rpm
  • deb
  • Alpine apk
  • pacman


  • systemd
  • sysV init
  • OpenRC init
  • Upstart


Original project: https://github.com/aelsabbahy/goss