Skip to content
Quick and Easy server testing/validation
Go Shell Ruby PHP Makefile Dockerfile DIGITAL Command Language
Branch: master
Clone or download
Fetching latest commit…
Cannot retrieve the latest commit at this time.
Type Name Latest commit message Commit time
Failed to load latest commit information.
development Run go fmt Jul 8, 2019
docs Remove global package option, instead add package-manager property May 16, 2019
integration Fix apt version to 1.6.11 in commander test Jul 8, 2019
outputs Add outputer skip and failure tests Jul 25, 2019
resource Run go fmt Jul 8, 2019
system Run go fmt Jul 8, 2019
util Run go fmt Jul 8, 2019
vendor Update gomega to v1.5.0 Apr 11, 2019
.gitignore Remove legacy integration tests Apr 18, 2019
.travis.yml Fix deployment Apr 23, 2019 Add CHANGELOG entry Jul 8, 2019
LICENSE Initial commit Oct 1, 2015
Makefile Update documentation Jul 9, 2019
add.go Run go fmt Jul 8, 2019
add_test.go Run go fmt Jul 8, 2019
app.go Run go fmt Jul 8, 2019
app_test.go Run go fmt Jul 8, 2019
go.mod Replace cli.Context with app.CliContext May 8, 2019
goss_config.go Remove unused code and add documentation Mar 3, 2019 Dynmically read latest goss release Mar 7, 2019 Ignore development dir in test coverage May 13, 2019
serve_test.go Run go fmt Jul 8, 2019
store.go Add template render tests Jul 8, 2019
store_test.go Run go fmt Jul 8, 2019
validate_test.go Run go fmt Jul 8, 2019

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

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

Manual installation

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

# (optional) dgoss docker wrapper (use 'master' for latest version)
curl -L -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:

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

You can’t perform that action at this time.