README ¶
Goss - Quick and Easy server validation
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 my blog post here.
Introduction
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
Installation
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://goss.rocks/install | sh
# Install v0.3.5 version to ~/bin
curl -fsSL https://goss.rocks/install | GOSS_VER=v0.3.5 GOSS_DST=~/bin sh
Manual installation
# See https://github.com/aelsabbahy/goss/releases for release versions
curl -L https://github.com/aelsabbahy/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/aelsabbahy/goss/_VERSION_/extras/dgoss/dgoss -o /usr/local/bin/dgoss
chmod +rx /usr/local/bin/dgoss
Full Documentation
Documentation is available here: https://github.com/aelsabbahy/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
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
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:
- Patterns
- Advanced Matchers
- Templates
title
andmeta
(arbitrary data) attributes are persisted when adding other resources withgoss add
Some examples:
user:
sshd:
title: UID must be between 50-100, GID doesn't matter. home is flexible
meta:
desc: Ensure sshd is enabled and running since it's needed for system management
sev: 5
exists: true
uid:
# Validate that UID is between 50 and 100
and:
gt: 50
lt: 100
home:
# Home can be any of the following
or:
- /var/empty/sshd
- /var/run/sshd
package:
kernel:
installed: true
versions:
# Must have 3 kernels and none of them can be 4.4.0
and:
- have-len: 3
- not:
contain-element: 4.4.0
# Loaded from --vars YAML/JSON file
{{.Vars.package}}:
installed: true
{{if eq .Env.OS "centos"}}
# This test is only when $OS environment variable is set to "centos"
libselinux:
installed: true
{{end}}
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.
Limitations
Currently goss only runs on Linux.
The following tests have limitations.
Package:
- rpm
- deb
- Alpine apk
- pacman
Service:
- systemd
- sysV init
- OpenRC init
- Upstart
Documentation ¶
Index ¶
- Constants
- Variables
- func AddResource(fileName string, gossConfig GossConfig, resourceName, key string, ...) error
- func AddResources(fileName, resourceName string, keys []string, c *cli.Context) error
- func AutoAddResource(fileName string, gossConfig GossConfig, key string, c *cli.Context, ...) error
- func AutoAddResources(fileName string, keys []string, c *cli.Context) error
- func NewTemplateFilter(varsFile string) func([]byte) []byte
- func RenderJSON(c *cli.Context) string
- func Serve(c *cli.Context)
- func Validate(c *cli.Context, startTime time.Time)
- func WriteJSON(filePath string, gossConfig GossConfig) error
- type GossConfig
- type TmplVars
Constants ¶
const ( UNSET = iota JSON YAML )
Variables ¶
var OutStoreFormat = UNSET
var TemplateFilter func(data []byte) []byte
Functions ¶
func AddResource ¶ added in v0.1.0
func AddResources ¶ added in v0.1.10
Simple wrapper to add multiple resources
func AutoAddResource ¶ added in v0.1.0
func AutoAddResources ¶ added in v0.1.10
Simple wrapper to add multiple resources
func NewTemplateFilter ¶ added in v0.3.0
func RenderJSON ¶
Reads json file recursively returning string
func WriteJSON ¶
func WriteJSON(filePath string, gossConfig GossConfig) error
Types ¶
type GossConfig ¶ added in v0.1.0
type GossConfig struct { Files resource.FileMap `json:"file,omitempty" yaml:"file,omitempty"` Packages resource.PackageMap `json:"package,omitempty" yaml:"package,omitempty"` Addrs resource.AddrMap `json:"addr,omitempty" yaml:"addr,omitempty"` Ports resource.PortMap `json:"port,omitempty" yaml:"port,omitempty"` Services resource.ServiceMap `json:"service,omitempty" yaml:"service,omitempty"` Users resource.UserMap `json:"user,omitempty" yaml:"user,omitempty"` Groups resource.GroupMap `json:"group,omitempty" yaml:"group,omitempty"` Commands resource.CommandMap `json:"command,omitempty" yaml:"command,omitempty"` DNS resource.DNSMap `json:"dns,omitempty" yaml:"dns,omitempty"` Processes resource.ProcessMap `json:"process,omitempty" yaml:"process,omitempty"` Gossfiles resource.GossfileMap `json:"gossfile,omitempty" yaml:"gossfile,omitempty"` KernelParams resource.KernelParamMap `json:"kernel-param,omitempty" yaml:"kernel-param,omitempty"` Mounts resource.MountMap `json:"mount,omitempty" yaml:"mount,omitempty"` Interfaces resource.InterfaceMap `json:"interface,omitempty" yaml:"interface,omitempty"` HTTPs resource.HTTPMap `json:"http,omitempty" yaml:"http,omitempty"` Matchings resource.MatchingMap `json:"matching,omitempty" yaml:"matching,omitempty"` }
func NewGossConfig ¶ added in v0.1.0
func NewGossConfig() *GossConfig
func ReadJSONData ¶
func ReadJSONData(data []byte, detectFormat bool) GossConfig
Reads json byte array returning GossConfig
func (*GossConfig) Resources ¶ added in v0.1.0
func (c *GossConfig) Resources() []resource.Resource