Skip to content

Command Line Interface

Usage

NAME:
   goss - Quick and Easy server validation

USAGE:
   goss [global options] command [command options] [arguments...]

VERSION:
   0.0.0

COMMANDS:
     validate, v  Validate system
     serve, s     Serve a health endpoint
     render, r    render gossfile after imports
     autoadd, aa  automatically add all matching resource to the test suite
     add, a       add a resource to the test suite
     help, h      Shows a list of commands or help for one command

GLOBAL OPTIONS:
   --gossfile value, -g value  Goss file to read from / write to (default: "./goss.yaml") [$GOSS_FILE]
   --vars value                json/yaml file containing variables for template [$GOSS_VARS]
   --vars-inline value         json/yaml string containing variables for template (overwrites vars) [$GOSS_VARS_INLINE]
   --package value             Package type to use [rpm, deb, apk, pacman]
   --help, -h                  show help
   --version, -v               print the version

Note

Most flags can be set by using environment variables, see --help for more info.

Global options

--gossfile/-g <gossfile>

The file to use when reading/writing tests. Use --gossfile - or -g - to read from STDIN.

Valid formats:

  • yaml (default)
  • json
--vars <varfile>

The file to read variables from when rendering gossfile templates.

Valid formats:

  • yaml (default)
  • json
--package <type>

The package type to check for.

Valid options are:

  • apk
  • deb
  • pacman
  • rpm

Commands

Commands are the actions goss can run.

  • add: add a single test for a resource
  • autoadd: automatically add multiple tests for a resource
  • render: renders and outputs the gossfile, importing all included gossfiles
  • serve: serves the gossfile validation as an HTTP endpoint on a specified address and port, so you can use your gossfile as a health report for the host
  • validate: runs the goss test suite on your server

add

Add system resource to test suite

goss add [--exclude-attr <pattern>] <test> [<test>]
goss a [--exclude-attr <pattern>] <test> [<test>]

This will add a test for a resource. Non existent resources will add a test to ensure they do not exist on the system. A sub-command resource type has to be provided when running add.

--exclude-attr
Ignore non-required attribute(s) matching the provided glob when adding a new resource, may be specified multiple times.

Example

goss add file /etc/passwd
goss a user nobody
goss add --exclude-attr home --exclude-attr shell user nobody
goss a --exclude-attr '*' user nobody

Resources types

Type Description
addr Verify if a remote address:port is reachable
command Run a command and validate the exit status and/or output
dns Resolves a dns name and validates the addresses
file Validate a file existence, permissions, stats (size, etc) and contents
goss Includes the contents of another gossfile
group can validate the existence and values of a group on the system
http Validate the HTTP response code, headers, and content of a URI
interface Validate the existence and values (es. the addresses) of a network interface
kernel-param Validate kernel parameters (sysctl values)
mount Validate the existence and options relative to a mount point
package Validate the status of a package using the package manager specified on the commandline with --package
port Validate the status of a local port, for example 80 or udp:123
process Validate the status of a process
service Validate if a service is running and/or enabled at boot
user Validate the existence and values of a user on the system

autoadd

Auto add all matching resources to test suite

goss autoadd [arguments...]
goss aa [arguments...]

Automatically adds all existing resources matching the provided argument.

Will automatically add the following matching resources:

  • file - only if argument contains /
  • group
  • package
  • port
  • process - Also adding any ports it's listening to (if run as root)
  • service
  • user

Will NOT automatically add:

  • addr
  • command - for safety
  • dns
  • http
  • interface
  • kernel-param
  • mount

Example

goss autoadd sshd

Generates the following 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

render

Render gossfile after importing all referenced gossfiles

goss render
goss r

This command allows you to keep your tests separated and render a single, valid, gossfile, by including them with the gossfile directive.

--debug
This prints the rendered golang template prior to printing the parsed JSON/YAML gossfile.

Example

$ cat goss_httpd_package.yaml
package:
  httpd:
    installed: true
    versions:

    - 2.2.15

$ cat goss_httpd_service.yaml
service:
  httpd:
    enabled: true
    running: true

$ cat goss_nginx_service-NO.yaml
service:
  nginx:
    enabled: false
    running: false

$ cat goss.yaml
gossfile:
  goss_httpd_package.yaml: {}
  goss_httpd_service.yaml: {}
  goss_nginx_service-NO.yaml: {}

$ goss -g goss.yaml render
package:
  httpd:
    installed: true
    versions:

    - 2.2.15
service:
  httpd:
    enabled: true
    running: true
  nginx:
    enabled: false
    running: false

serve

Serve a health endpoint

goss serve [<opts>...]
goss s [<opts>...]

serve exposes the goss test suite as a health endpoint on your server. The end-point will return the stest results in the format requested and an http status of 200 or 503.

serve will look for a test suite in the same order as validate

--cache <duration>, -c <duration>
Time to cache the results (default: 5s)
--endpoint <endpoint>, -e <endpoint>
Endpoint to expose (default: /healthz)
--format <format>, -f <format>
Output format, same as validate
--listen-addr [ip]:port, -l [ip]:port
Address to listen on (default: :8080)
--loglevel <level>, -L <level>

Goss logging verbosity level (default: INFO). Lower levels of tracing include all upper levels traces also (ie. INFO include WARN and ERROR). level can be one of:

  • ERROR - Critical errors that halt goss or significantly affect its functionality, requiring immediate intervention.
  • WARN - Non-critical issues that may require attention, such as overwritten keys or deprecated features.
  • INFO - General operational messages, useful for tasks where a more structured output is needed (e.g. goss serve).
  • DEBUG - Information useful for the goss user to debug.
  • TRACE - Detailed internal system activities useful for goss developers to debug.
--max-concurrent <num>
Max number of tests to run concurrently

Example

$ goss serve &
$ curl http://localhost:8080/healthz
# JSON endpoint
$ goss serve --format json &
$ curl localhost:8080/healthz
# rspecish output format in response via content negotiation
goss serve --format json &
curl -H "Accept: application/vnd.goss-rspecish" localhost:8080/healthz

The application/vnd.goss-{output format} media type can be used in the Accept request header to determine the response's content-type. You can also Accept: application/json to get back application/json.

validate

Validate the system

goss validate [<opts>...]
goss v [<opts>...]

validate runs the goss test suite on your server. Prints an rspec-like (by default) output of test results. Exits with status 0 on success, non-0 otherwise.

--format <format>, -f <format>

Output format. Can be one of:

  • documentation - Verbose test results
  • json - Detailed test result on a single line (See pretty format option)
  • junit
  • nagios - Nagios/Sensu compatible output /w exit code 2 for failures
  • rspecish (default) - Similar to rspec output
  • tap
  • prometheus - Prometheus compatible output.
  • silent - No output. Avoids exposing system information (e.g. when serving tests as a healthcheck endpoint)
--format-options, -o

Output format option:

  • perfdata - Outputs Nagios "performance data". Applies to nagios output
  • verbose - Gives verbose output. Applies to nagios and prometheus output
  • pretty - Pretty printing for the json output
  • sort - Sorts the results
--loglevel <level>, -L <level>

Goss logging verbosity level (default: INFO). Lower levels of tracing include all upper levels traces also (ie. INFO includes WARN, ERROR and FATAL outputs). level can be one of :

  • TRACE - Print details for each check, successful or not and all incoming healthchecks
  • DEBUG - Print details of summary response to healthchecks including remote IP address, return code and full body
  • INFO - Print summary when all checks run OK
  • WARN - Print summary and corresponding checks when encountering some failures
  • ERROR - Not used for now (will not print anything)
  • FATAL - Not used for now (will not print anything)
--max-concurrent <num>
Max number of tests to run concurrently
--color/--no-color
Force color or disable color
--retry-timeout <timeout>, -r <timeout>

Retry on failure so long as elapsed + sleep time is less than this

default: 0

--sleep <duration>, -s <duration>

Time to sleep between retries

default: 1s

Example

$ goss validate --format documentation
File: /etc/hosts: exists: matches expectation: [true]
DNS: localhost: resolvable: matches expectation: [true]
[...]
Total Duration: 0.002s
Count: 10, Failed: 2, Skipped: 0

$ curl -s https://static/or/dynamic/goss.json | goss validate
...F.F
[...]
Total Duration: 0.002s
Count: 6, Failed: 2, Skipped: 0

$ goss render | ssh remote-host 'goss -g - validate'
......

Total Duration: 0.002s
Count: 6, Failed: 0, Skipped: 0

$ goss validate --format nagios -o verbose -o perfdata
GOSS CRITICAL - Count: 76, Failed: 1, Skipped: 0, Duration: 1.009s|total=76 failed=1 skipped=0 duration=1.009s
Fail 1 - DNS: localhost: addrs: doesn't match, expect: [["127.0.0.1","::1"]] found: [["127.0.0.1"]]
$ echo $?
2