goss(1)
Goss is a quick and easy server validation tool that checks system state against a YAML specification file.
Synopsis
goss [OPTION] COMMAND [ARG]...Description
Goss is a serverspec alternative for validating a server's configuration. It reads a YAML specification file defining expected system state (packages, services, ports, files, users, etc.) and validates that the actual system matches that specification.
Unlike traditional testing frameworks, goss is lightweight, fast, and designed for quick validation during deployment, configuration management, and infrastructure testing. It outputs simple pass/fail results and can integrate into CI/CD pipelines.
Common options
| Flag | What it does |
|---|---|
-g, --gossfile FILE | Path to the goss specification file (default: goss.yaml) |
-v, --vars FILE | Path to variables YAML file for templating the gossfile |
-o, --outputter FORMAT | Output format: json, tap, junit, nagios, prometheus (default: rspecish) |
-f, --format FORMAT | Alias for --outputter |
--timeout DURATION | Timeout for each test, e.g. 5s, 2m (default: 5s) |
-s, --sleep DURATION | Sleep duration between retries for slow-to-start services |
-r, --retry TIMES | Number of times to retry failed tests before giving up |
--use-alpha | Enable alpha features |
-h, --help | Display help message |
Examples
Run validation using default goss.yaml file in current directory
goss validateValidate using a specific gossfile location
goss -g /etc/goss/server.yaml validateOutput validation results in JSON format and parse with jq
goss validate -o json | jqValidate with variable substitution from vars.yaml file
goss -v vars.yaml validateInteractively add and edit test specifications in the gossfile
goss editDisplay the parsed gossfile with variables substituted
goss renderValidate with 10-second timeout per test and retry failures 3 times
goss validate --timeout 10s --retry 3Validate and check exit code for integration with monitoring systems
goss validate -o nagios && echo "Server OK" || echo "Server failed"