### Manually Install Latest Goss

Source: https://github.com/goss-org/goss/blob/master/README.md

Downloads and installs the latest Goss binary to /usr/local/bin and makes it executable. Also installs dgoss.

```bash
curl -L https://github.com/goss-org/goss/releases/latest/download/goss-linux-amd64 -o /usr/local/bin/goss
chmod +rx /usr/local/bin/goss

curl -L https://github.com/goss-org/goss/releases/latest/download/dgoss -o /usr/local/bin/dgoss
# Alternatively, using the latest master
# curl -L https://raw.githubusercontent.com/goss-org/goss/master/extras/dgoss/dgoss -o /usr/local/bin/dgoss
chmod +rx /usr/local/bin/dgoss
```

--------------------------------

### Install kgoss and goss via CLI

Source: https://github.com/goss-org/goss/blob/master/extras/kgoss/README.md

Automates the installation of kgoss and goss using curl and jq. Requires a GitHub personal access token and jq installed. It downloads the latest release assets and places them in a specified directory.

```shell
token=<personal_access_token>
username=$(whoami)
dest_dir=${HOME}/bin

host=raw.githubusercontent.com
repo=goss-org/goss

## install kgoss
curl -sSL -u "${username}:${token}" -H 'Accept: application/vnd.github.v3.raw' -o "${dest_dir}/kgoss" \
  https://${host}/api/v3/repos/${repo}/contents/extras/kgoss/kgoss
chmod a+rx "${dest_dir}/kgoss"

## install goss
if [[ ! $(which jq) ]]; then echo "jq is required, get from https://stedolan.github.io/jq"; fi
version=v0.4.8
arch=amd64
host=github.com

dl_url=$(curl -sSL -u "${username}:${token}" https://${host}/api/v3/repos/${repo}/releases \
  | jq -r ".[] | select (.name == \"${version}\") | .assets[] | select (.name == \"goss-linux-${arch}\") | .url")
curl -sSL -u "${username}:${token}" -H 'Accept: application/octet-stream' -o "${dest_dir}/goss" $dl_url
chmod a+rx "${dest_dir}/goss"

# If `goss` is not in your path, export a GOSS_PATH variable:
export GOSS_PATH=${dest_dir}/goss

# Now you can use kgoss as described below:
# kgoss edit ...
# kgoss run ...
```

--------------------------------

### Install Latest Goss with Curl

Source: https://github.com/goss-org/goss/blob/master/README.md

Installs the latest version of Goss to /usr/local/bin. Not recommended for production.

```bash
curl -fsSL https://goss.rocks/install | sh
```

--------------------------------

### String Matchers Example

Source: https://github.com/goss-org/goss/blob/master/docs/gossfile.md

Demonstrates various string matching conditions including exact match, prefix, suffix, regex, and substring containment.

```yaml
matching:
example:
    content: 42
    matches:
    and:
        - '42'
        - have-prefix: '4'
        - have-suffix: '2'
        - match-regexp: '\d{2}'
        - contain-substring: '2'
```

--------------------------------

### Array Matchers Example

Source: https://github.com/goss-org/goss/blob/master/docs/gossfile.md

Shows how to match array contents using various strategies like containing elements, exact equality, and set-based comparisons.

```yaml
matching:
example:
    content: [foo, bar, moo]
    matches:
    and:
        - contain-elements: [foo, bar]
        - [foo, bar] # same as above
        - equal: [foo, bar, moo] # order matters, exact match
        - consist-of: [foo, have-prefix: m, bar] # order doesn't matter, can use matchers
        - contain-element:
            have-prefix: b
```

--------------------------------

### Run Goss Container

Source: https://github.com/goss-org/goss/blob/master/docs/container_image.md

Starts a Goss container. This can be used to mount its volumes later.

```sh
docker run --name goss ghcr.io/goss-org/goss goss
```

--------------------------------

### Manually Install Specific Goss Version

Source: https://github.com/goss-org/goss/blob/master/README.md

Downloads and installs a specific version of Goss and dgoss binaries to /usr/local/bin. Ensure the VERSION variable is set correctly.

```bash
# See https://github.com/goss-org/goss/releases for release versions
VERSION=v0.4.8
curl -L "https://github.com/goss-org/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)
VERSION=v0.4.8
curl -L "https://github.com/goss-org/goss/releases/download/${VERSION}/dgoss" -o /usr/local/bin/dgoss
chmod +rx /usr/local/bin/dgoss
```

--------------------------------

### Dynamic Goss Configuration with Vars and Env

Source: https://github.com/goss-org/goss/blob/master/docs/gossfile.md

This example shows how to create a dynamic Goss configuration using a vars file and environment variables. It demonstrates looping through packages based on the OS environment variable and conditionally including tests.

```yaml
centos:
  packages:
    kernel:
      - "4.9.11-centos"
      - "4.9.11-centos2"
debian:
  packages:
    kernel:
      - "4.9.11-debian"
      - "4.9.11-debian2"
users:
  - user1
  - user2
```

```yaml+jinja
package:
# Looping over a variables defined in a vars.yaml using $OS environment variable as a lookup key
{{range $name, $vers := index .Vars .Env.OS "packages"}}
  {{$name}}:
    installed: true
    versions:
    {{range $vers}}
      - {{.}}
    {{end}}
{{end}}

# This test is only when the OS environment variable matches the pattern
{{if .Env.OS | regexMatch "[Cc]ent(OS|os)"}}
  libselinux:
    installed: true
{{end}}

# Loop over users
user:
{{range .Vars.users}}
  {{.}}: 
    exists: true
    groups:
    - {{.}}
    home: /home/{{.}}
    shell: /bin/bash
{{end}}


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

--------------------------------

### Goss Package Test Generation

Source: https://github.com/goss-org/goss/blob/master/docs/gossfile.md

Example of YAML generated by `goss add package nginx` for an installed package.

```yaml
package:
  nginx:
    installed: true
    versions:
    - 1.17.8
```

--------------------------------

### Numeric Matchers Example

Source: https://github.com/goss-org/goss/blob/master/docs/gossfile.md

Illustrates numeric matching with exact values, floating-point numbers, and range comparisons (greater than, less than).

```yaml
matching:
example:
    content: "42"
    matches:
    and:
        - 42
        - 42.0
        - gt: 40
        - lt: 45
```

--------------------------------

### Install dgoss and Configure Goss Path on Mac OSX

Source: https://github.com/goss-org/goss/blob/master/extras/dgoss/README.md

Installs dgoss and downloads a specific goss version. Sets environment variables GOSS_PATH and DGOSS_TEMP_DIR for dgoss to function correctly on Mac OSX.

```shell
# Install dgoss
curl -L https://raw.githubusercontent.com/goss-org/goss/master/extras/dgoss/dgoss -o /usr/local/bin/dgoss
chmod +rx /usr/local/bin/dgoss

# Download desired goss version to your preferred location (e.g. v0.4.8)
curl -L https://github.com/goss-org/goss/releases/download/v0.4.8/goss-linux-amd64 -o ~/Downloads/goss-linux-amd64

# Set your GOSS_PATH to the above location
export GOSS_PATH=~/Downloads/goss-linux-amd64

# Set DGOSS_TEMP_DIR to the tmp directory in your home, since /tmp is private on Mac OSX
export DGOSS_TEMP_DIR=~/tmp

# Use dgoss
dgoss edit ...
dgoss run ...
```

--------------------------------

### Goss File with Jinja2 Templates and Advanced Matchers

Source: https://github.com/goss-org/goss/blob/master/README.md

Example of a `goss.yaml` file using Jinja2 templating for conditional tests and advanced matchers for validating user UIDs, package versions, and OS-specific packages.

```yaml+jinja
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}}
```

--------------------------------

### Validate Rendered Goss File with yajsv

Source: https://github.com/goss-org/goss/blob/master/README.md

Use the `yajsv` command-line tool to validate a rendered Goss YAML file against a JSON schema. This example assumes `yajsv` is installed and the schema is available.

```bash
# The following example is for a Linux AMD64 host
$ curl -LO https://github.com/neilpa/yajsv/releases/download/v1.4.1/yajsv.linux.amd64
$ chmod a+x yajsv.linux.amd64
$ sudo mv yajsv.linux.amd64 /usr/sbin/yajsv

$ yajsv -s goss-json-schema.yaml rendered_goss.yaml

rendered_goss.yaml: fail: process.chrome: skip is required
rendered_goss.yaml: fail: service.sshd: skip is required
1 of 1 failed validation
rendered_goss.yaml: fail: process.chrome: skip is required
rendered_goss.yaml: fail: service.sshd: skip is required
```

--------------------------------

### Install Specific Goss Version with Curl

Source: https://github.com/goss-org/goss/blob/master/README.md

Installs a specific version of Goss to a custom directory. Use GOSS_VER to specify the version and GOSS_DST for the destination.

```bash
curl -fsSL https://goss.rocks/install | GOSS_VER=v0.4.8 GOSS_DST=~/bin sh
```

--------------------------------

### Edit Container Configuration Interactively

Source: https://github.com/goss-org/goss/blob/master/extras/kgoss/README.md

Use this command to launch a container, install goss, and enter an interactive shell for editing goss configurations. Environment variables can be passed using the `-e` flag, and the image is specified with `-i`.

```bash
kgoss edit -e JENKINS_OPTS="--httpPort=8080 --httpsPort=-1" -e JAVA_OPTS="-Xmx1048m" -i jenkins:alpine
```

--------------------------------

### Validate Package State

Source: https://github.com/goss-org/goss/blob/master/docs/gossfile.md

Checks if a package is installed and optionally verifies its version. Requires the `--package <format>` command-line parameter.

```yaml
package:
  httpd:
    # required attributes
    installed: true
    # optional attributes
    # defaults to hash key
    name: httpd
    versions:
    - 2.2.15
    skip: false
```

--------------------------------

### Download kgoss Manually

Source: https://github.com/goss-org/goss/blob/master/extras/kgoss/README.md

Use curl to download the kgoss script directly. This is useful for manual installation or when a CLI-based approach is not preferred.

```shell
curl -sSLO \
  https://raw.githubusercontent.com/goss-org/goss/master/extras/kgoss/kgoss
```

--------------------------------

### Goss Default Configuration for SSHD

Source: https://github.com/goss-org/goss/blob/master/README.md

This is an example of a `goss.yaml` file generated by `goss autoadd sshd`, defining tests for TCP ports, services, users, and groups.

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

--------------------------------

### Validate Goss Tests

Source: https://github.com/goss-org/goss/blob/master/README.md

Run Goss tests once using the `goss validate` command. This example shows a successful validation with a count of 15 tests and 0 failures.

```console
$ goss validate
...............

Total Duration: 0.021s # <- yeah, it's that fast..
Count: 15, Failed: 0
```

--------------------------------

### Edit dgoss Configuration for a Container

Source: https://github.com/goss-org/goss/blob/master/extras/dgoss/README.md

Use 'dgoss edit' to launch a container, install goss, and provide an interactive shell. Configuration files are copied out upon exiting the shell.

```bash
dgoss edit -e JENKINS_OPTS="--httpPort=8080 --httpsPort=-1" -e JAVA_OPTS="-Xmx1048m" jenkins:alpine
```

--------------------------------

### Edit goss tests for a docker-compose service

Source: https://github.com/goss-org/goss/blob/master/extras/dcgoss/README.md

Launch a container for a docker-compose service, install goss, and provide an interactive shell to edit goss tests. Exits will copy goss.yaml and goss_wait.yaml back to the current directory.

```bash
dcgoss edit db
```

--------------------------------

### Goss Kernel Parameter Value Test

Source: https://github.com/goss-org/goss/blob/master/docs/gossfile.md

Tests the 'value' attribute of a kernel parameter. This example shows a direct string comparison, where the expected value must match the system's reported value.

```yaml
kernel-param:
  net.core.somaxconn:
    value: "128"
```

--------------------------------

### Validate System via SSH

Source: https://github.com/goss-org/goss/blob/master/docs/cli.md

Renders goss tests and pipes them to a remote host via SSH for validation. Useful for remote validation without installing goss locally on the target.

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

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

--------------------------------

### Build Goss from Source

Source: https://github.com/goss-org/goss/blob/master/README.md

Compiles the Goss binary from the source code using the make build command.

```bash
make build
```

--------------------------------

### Run Windows Serve Integration Test

Source: https://github.com/goss-org/goss/blob/master/docs/platforms.md

Execute the integration test for the 'serve' command on Windows. This is a special-case test requiring a persistent process.

```bash
make "test-int-serve-windows-amd64"
```

--------------------------------

### Goss CLI Help Output

Source: https://github.com/goss-org/goss/blob/master/docs/cli.md

Displays the main help information for the Goss CLI, listing available commands and global options.

```console
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

```

--------------------------------

### Dockerfile with Startup Delay

Source: https://github.com/goss-org/goss/blob/master/docs/container_image.md

Uses the Goss image as a base and configures the CMD to run Goss validation with a retry timeout before executing the main command.

```dockerfile
FROM ghcr.io/goss-org/goss:latest

COPY goss/ /goss/

# Alternatively, the -r option can be set
# using the GOSS_RETRY_TIMEOUT env variable
CMD goss -g /goss/goss.yaml validate -r 5m && exec real_comand..
```

--------------------------------

### Render Gossfile with Imports

Source: https://github.com/goss-org/goss/blob/master/docs/cli.md

Renders a single gossfile by importing and combining multiple referenced gossfiles. Use this to manage test suites in a modular fashion. The --debug flag shows the rendered Go template before parsing.

```console
goss render
goss r
```

```yaml
gossfile:
  goss_httpd_package.yaml: {}
  goss_httpd_service.yaml: {}
  goss_nginx_service-NO.yaml: {}
```

```console
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
```

```yaml
package:
  httpd:
    installed: true
    versions:
    - 2.2.15
service:
  httpd:
    enabled: true
    running: true
  nginx:
    enabled: false
    running: false
```

--------------------------------

### Run macOS Serve Integration Test

Source: https://github.com/goss-org/goss/blob/master/docs/platforms.md

Execute the integration test for the 'serve' command on macOS. This is a special-case test requiring a persistent process.

```bash
make "test-int-serve-darwin-amd64"
```

--------------------------------

### Validate System with Documentation Format

Source: https://github.com/goss-org/goss/blob/master/docs/cli.md

Runs the goss test suite and outputs verbose test results in a documentation-like format. Useful for detailed human-readable reports.

```console
$ 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
```

--------------------------------

### Read File Content for Token Extraction

Source: https://github.com/goss-org/goss/blob/master/docs/gossfile.md

Demonstrates using the `readFile` function to read a file's content and `findStringSubmatch` to extract specific information using regular expressions with named capture groups. This is useful for parsing configuration files or tokens.

```go
{{ $regexDBrc := "\'mysql:\/\/(?P<login>[a-z0-9]+):(?P<password>[a-z0-9]+)@localhost\/(?P<database>roundcube_[a-z0-9]+)\';"}}

{{ $rcConf := readFile /home/user/roundcube/config.inc.php | findStringSubmatch $regexDBrc }}
{{ $UserDBrc := get $rcConf "login" }}
{{ $PassDBrc  := get $rcConf "password" }}
{{ $DBrc := get $rcConf "database" }}
```

--------------------------------

### Array Matchers No Longer Allow Duplicates (v0.4.x)

Source: https://github.com/goss-org/goss/blob/master/docs/migrations.md

In Goss v0.4.x, array matchers like user.groups do not permit duplicate entries. This example shows a valid configuration for v0.4.x.

```yaml
user:
  root:
    exists: true
    groups:
      - have-prefix: r
```

--------------------------------

### Serve Goss Tests with RSpec-like Response

Source: https://github.com/goss-org/goss/blob/master/README.md

Serve Goss tests and request an rspec-like response via content negotiation using the `Accept` header.

```bash
$ goss serve --format json &
```

```bash
$ curl -H "Accept: application/vnd.goss-rspecish" localhost:8080/healthz
```

--------------------------------

### Set Goss Files Copy Strategy

Source: https://github.com/goss-org/goss/blob/master/extras/dgoss/README.md

Configure GOSS_FILES_STRATEGY to 'mount' to use a volume and stream logs, or 'cp' to use 'docker cp'. 'cp' is required when the container daemon is not local.

```bash
export GOSS_FILES_STRATEGY=cp
```

--------------------------------

### Goss Basic String Matching

Source: https://github.com/goss-org/goss/blob/master/docs/gossfile.md

Demonstrates basic equality matching for string attributes. The 'matches' value must be exactly equal to the 'content' value.

```yaml
matching:
  basic_string:
    content: 'foo'
    matches: 'foo'

user:
  nfsnobody:
    exists: true
    uid: 65534
```

--------------------------------

### Specify Container Runtime

Source: https://github.com/goss-org/goss/blob/master/extras/dgoss/README.md

Set CONTAINER_RUNTIME to 'docker' or 'podman' to choose the container runtime. 'podman' may require a run command like 'sleep infinity' if only an image is provided.

```bash
export CONTAINER_RUNTIME=podman
```

```bash
dgoss run --container-runtime podman alpine:latest sleep infinity
```

--------------------------------

### Correct Goss File Structure

Source: https://github.com/goss-org/goss/blob/master/docs/gossfile.md

Shows the CORRECT way to write a goss file by grouping entries of the same type under a single declaration.

```yaml
file:
  /etc/httpd/conf/httpd.conf:
    exists: true
  /var/www/html:
    filetype: directory
    exists: true

service:
  httpd:
    enabled: true
    running: true
```

--------------------------------

### Use 'cp' strategy for copying goss files

Source: https://github.com/goss-org/goss/blob/master/extras/dcgoss/README.md

Force dcgoss to use the 'cp' strategy for copying goss files into the container, instead of mounting. This is necessary when the docker daemon is not local.

```bash
GOSS_FILES_STRATEGY=cp dcgoss run db
```

--------------------------------

### Specify Additional Files to Copy

Source: https://github.com/goss-org/goss/blob/master/extras/dgoss/README.md

Use GOSS_ADDITIONAL_COPY_PATH to recursively copy additional directories into the container alongside goss.yaml.

```bash
export GOSS_ADDITIONAL_COPY_PATH=./scripts:./config
```

--------------------------------

### Benchmark Goss Validation (New Laptop)

Source: https://github.com/goss-org/goss/wiki/Benchmarks

Measures the time taken for Goss validation on a new laptop with a warm filesystem cache. This provides a baseline performance metric.

```bash
$ time goss validate --format nagios
GOSS OK - Count: 1122, Failed: 0, Duration: 0.052s

real	0m0.057s
user	0m0.104s
sys	0m0.091s
```

--------------------------------

### Benchmark Goss Validation (Old Laptop)

Source: https://github.com/goss-org/goss/wiki/Benchmarks

Measures the time taken for Goss validation on an old laptop with a warm filesystem cache. Results are near instantaneous, indicating efficient caching.

```bash
$ time goss validate --format nagios
GOSS OK - Count: 1049, Failed: 0, Duration: 0.080s

real	0m0.087s
user	0m0.189s
sys	0m0.152s
```

--------------------------------

### Generate SSHD Tests with Goss Autoadd

Source: https://github.com/goss-org/goss/blob/master/README.md

Use the `goss autoadd` command to generate initial tests for a service like sshd. Running as root allows detection of listening ports.

```bash
sudo goss autoadd sshd
```

--------------------------------

### Add System Resource Test

Source: https://github.com/goss-org/goss/blob/master/docs/cli.md

Use 'goss add' or 'goss a' to add a test for a specific system resource. Non-existent resources will be tested to ensure they do not exist. The '--exclude-attr' flag can be used to ignore specific attributes when adding a resource.

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

```console
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
```

--------------------------------

### Run dgoss to Test a Container

Source: https://github.com/goss-org/goss/blob/master/extras/dgoss/README.md

Substitute the container runtime command with dgoss run to validate a container. It expects a './goss.yaml' file and optionally uses './goss_wait.yaml' for pre-checks.

```bash
docker run -e JENKINS_OPTS="--httpPort=8080 --httpsPort=-1" -e JAVA_OPTS="-Xmx1048m" jenkins:alpine
```

```bash
dgoss run -e JENKINS_OPTS="--httpPort=8080 --httpsPort=-1" -e JAVA_OPTS="-Xmx1048m" jenkins:alpine
```

--------------------------------

### Benchmark Goss Validation (New Laptop, Dropped Cache)

Source: https://github.com/goss-org/goss/wiki/Benchmarks

Measures the time taken for Goss validation on a new laptop after dropping the filesystem cache. This highlights the performance impact of a cold cache.

```bash
$ sudo bash -c 'sync && echo 3 > /proc/sys/vm/drop_caches'
$ time goss validate --format nagios
GOSS OK - Count: 1122, Failed: 0, Duration: 0.060s

real	0m0.085s
user	0m0.134s
sys	0m0.093s
```

--------------------------------

### Benchmark Goss Validation (Old Laptop, Dropped Cache)

Source: https://github.com/goss-org/goss/wiki/Benchmarks

Measures the time taken for Goss validation on an old laptop after dropping the filesystem cache. This demonstrates a significant increase in validation time due to the cold cache.

```bash
$ sudo bash -c 'sync && echo 3 > /proc/sys/vm/drop_caches'
$ time goss validate --format nagios
GOSS OK - Count: 1049, Failed: 0, Duration: 2.249s

real	0m2.289s
user	0m0.195s
sys	0m0.288s
```

--------------------------------

### Autoadd Resources to Goss Test Suite

Source: https://github.com/goss-org/goss/blob/master/docs/cli.md

Automatically adds existing resources that match the provided argument to the test suite. Use this to quickly generate baseline tests for services, users, or packages.

```console
goss autoadd [arguments...]
goss aa [arguments...]
```

```console
goss autoadd sshd
```

--------------------------------

### Run Darwin and Windows Integration Tests

Source: https://github.com/goss-org/goss/blob/master/docs/platforms.md

Execute integration tests for Darwin (macOS) and Windows platforms. These commands filter goss spec files by OS name and run the 'validate' command against them.

```bash
make test-int-validate-darwin-amd64
```

```bash
make test-int-validate-windows-amd64
```

--------------------------------

### Import Other Gossfiles

Source: https://github.com/goss-org/goss/blob/master/docs/gossfile.md

Allows importing other Gossfiles, useful for organizing large test suites or creating profiles. Glob patterns can be used to match multiple files. The 'skip' attribute prevents processing of a specified gossfile.

```yaml
gossfile:
  myapplication:
    file: myapp_gossfile.yaml
    skip: false
  *.yaml:
    skip: true
  goss_httpd.yaml: {}
  /etc/goss.d/*.yaml: {}
```

--------------------------------

### Enable debug output for dcgoss

Source: https://github.com/goss-org/goss/blob/master/extras/dcgoss/README.md

Run dcgoss commands with debug output enabled. The temporary directory with container output will not be cleaned up when DEBUG is true.

```bash
DEBUG=true dcgoss edit db
```

--------------------------------

### Dockerfile with HEALTHCHECK

Source: https://github.com/goss-org/goss/blob/master/docs/container_image.md

Uses the Goss image as a base and configures a Docker HEALTHCHECK to validate Goss configurations at a specified interval.

```dockerfile
FROM ghcr.io/goss-org/goss:latest

COPY goss/ /goss/
HEALTHCHECK --interval=1s --timeout=6s CMD goss -g /goss/goss.yaml validate

# your stuff..
```

--------------------------------

### Specify a custom goss.yaml file name

Source: https://github.com/goss-org/goss/blob/master/extras/dcgoss/README.md

Run dcgoss using a different name for the goss test file. Useful when managing multiple configurations for the same image.

```bash
GOSS_FILE=goss_config1.yaml dcgoss run db
```

--------------------------------

### Run goss test on a docker-compose service

Source: https://github.com/goss-org/goss/blob/master/extras/dcgoss/README.md

Execute goss tests against a specified service defined in docker-compose.yml. Assumes docker-compose.yml and goss.yaml are in the current directory.

```bash
dcgoss run db
```

--------------------------------

### Serve Goss Tests as JSON Health Endpoint

Source: https://github.com/goss-org/goss/blob/master/README.md

Serve Goss tests with a JSON formatted health endpoint by using the `--format json` flag.

```bash
$ goss serve --format json &
```

```bash
$ curl localhost:8080/healthz
```

--------------------------------

### Validate System from JSON Input

Source: https://github.com/goss-org/goss/blob/master/docs/cli.md

Validates system tests by piping JSON output from a curl command into goss. Displays a compact output format.

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

--------------------------------

### Incorrect Goss File Structure

Source: https://github.com/goss-org/goss/blob/master/docs/gossfile.md

Demonstrates a WRONG way to write a goss file where duplicate keys like 'file' overwrite previous entries.

```yaml
file:
  /etc/httpd/conf/httpd.conf:
    exists: true

service:
  httpd:
    enabled: true
    running: true

file:
  /var/www/html:
    filetype: directory
    exists: true
```

--------------------------------

### Goss Validation Output (Correct File)

Source: https://github.com/goss-org/goss/blob/master/docs/gossfile.md

Console output from validating the correct goss file, showing all tests were executed.

```console
$ goss validate --format documentation
File: /var/www/html: exists: matches expectation: [true]
File: /var/www/html: filetype: matches expectation: ["directory"]
File: /etc/httpd/conf/httpd.conf: exists: matches expectation: [true]
Service: httpd: enabled: matches expectation: [true]
Service: httpd: running: matches expectation: [true]

Total Duration: 0.014s
Count: 10, Failed: 0, Skipped: 0
```

--------------------------------

### RPM Version Formatting Change (v0.4.x)

Source: https://github.com/goss-org/goss/blob/master/docs/migrations.md

The RPM version matching has been updated to include the full EVR (Epoch:Version-Release) for future comparison capabilities.

```bash
rpm -q --nosignature --nohdrchk --nodigest --qf '%|EPOCH?{%{EPOCH}:}:{}|%{VERSION}-%{RELEASE}\n' package_name
```

--------------------------------

### Goss File Content Matching with io.Readers

Source: https://github.com/goss-org/goss/blob/master/docs/gossfile.md

Validates file contents using line-by-line matching. Supports direct string containment, negation ('!'), escaped negation ('\!'), and regular expressions. Regex support is based on Golang's regex engine.

```yaml
file:
  /tmp/test.txt:
    exists: true
    contents:
    - "foo"
    - "!bar"
    - "/[Gg]oss/"
```

--------------------------------

### Semver Constraint Matching

Source: https://github.com/goss-org/goss/blob/master/docs/gossfile.md

Validates version strings against semantic versioning constraints and ranges. Supports standard semver syntax and negation.

```yaml
matching:
semver:
    content:
    - 1.0.1
    - 1.9.9
    matches:
    semver-constraint: ">1.0.0 <2.0.0 !=1.5.0"
semver2:
    content:
    - 1.0.1
    - 1.5.0
    - 1.9.9
    matches:
    not:
        semver-constraint: ">1.0.0 <2.0.0 !=1.5.0"
semver3:
    content: 1.0.1
    matches:
    semver-constraint: ">5.0.0 || < 1.5.0"
```

--------------------------------

### Render and Validate Goss with Debugging

Source: https://github.com/goss-org/goss/blob/master/docs/gossfile.md

Commands to validate, render, or render with debugging enabled for a Goss configuration that uses variables and environment lookups. This helps in verifying the dynamic test generation.

```console
# To validate:
$ OS=centos goss --vars vars.yaml validate
# To render:
$ OS=centos goss --vars vars.yaml render
# To render with debugging enabled:
$ OS=centos goss --vars vars.yaml render --debug
```

--------------------------------

### Render Goss File for JSON Schema Validation

Source: https://github.com/goss-org/goss/blob/master/README.md

Render a Goss file with templates into a plain YAML file using `goss render`. This rendered file can then be validated against a JSON schema.

```console
$ cd docs
$ goss --vars ./vars.yaml render > rendered_goss.yaml
```

--------------------------------

### Run Container Validation with Environment Variables

Source: https://github.com/goss-org/goss/blob/master/extras/kgoss/README.md

Use this command to run goss tests within a container, specifying custom environment variables for the container. The `-i` flag is required to specify the image URL.

```bash
kgoss run -e JENKINS_OPTS="--httpPort=8080 --httpsPort=-1" -e JAVA_OPTS="-Xmx1048m" -i jenkins:alpine
```

--------------------------------

### Use Sprig's upper Function

Source: https://github.com/goss-org/goss/blob/master/docs/gossfile.md

Demonstrates using the 'upper' function from the Sprig library to convert a string to uppercase and 'repeat' to duplicate it multiple times within a template. This is useful for generating test data or assertions.

```yaml+jinja
matching:
  sping_basic:
    content: {{ "hello!" | upper | repeat 5 }}
    matches:
      match-regexp: "HELLO!HELLO!HELLO!HELLO!HELLO!"
```

--------------------------------

### Serve Goss Tests as Health Endpoint

Source: https://github.com/goss-org/goss/blob/master/README.md

Run Goss tests as a background service that exposes a health check endpoint. The default format is human-readable.

```bash
$ goss serve &
```

```bash
$ curl localhost:8080/healthz
```

--------------------------------

### Specify custom path for goss files

Source: https://github.com/goss-org/goss/blob/master/extras/dcgoss/README.md

Use dcgoss with a custom directory for goss configuration files. This overrides the default current directory.

```bash
GOSS_FILES_PATH=db dcgoss edit db
```

--------------------------------

### Validate Process Running

Source: https://github.com/goss-org/goss/blob/master/docs/gossfile.md

Checks if a process is running based on its binary name. Note that this inspects the binary name, not the full process name. Use `cat -E /proc/<PID>/comm` to find the binary name.

```yaml
process:
  chrome:
    # required attributes
    running: true
    # optional attributes
    # defaults to hash key
    comm: chrome
    skip: false
```

--------------------------------

### Validate Mount Point

Source: https://github.com/goss-org/goss/blob/master/docs/gossfile.md

Checks mount point attributes such as existence, options, source, filesystem type, and usage percentage. The mount point path defaults to the key.

```yaml
mount:
  /home:
    # required attributes
    exists: true
    # optional attributes
    # defaults to hash key
    timeout: 1000
    mountpoint: /home
    opts:
    - rw
    - relatime
    # This maps to the per-superblock options, see:
    # https://man7.org/linux/man-pages/man5/proc.5.html
    # https://man7.org/linux/man-pages/man2/mount.2.html
    vfs-opts:
    - rw
    source: /dev/mapper/fedora-home
    filesystem: xfs
    usage: #% of blocks used in this mountpoint
      lt: 95
```

--------------------------------

### Goss File Content Matching with Advanced Matchers

Source: https://github.com/goss-org/goss/blob/master/docs/gossfile.md

An alternative way to express file content validation using 'and', 'not', and 'contain-element' with optional regex matching. This provides a more structured approach compared to inline string matching.

```yaml
file:
  /tmp/test.txt:
    exists: true
    contents:
    and:
      - contain-element: "foo"
      - not: {contain-element: "bar"}
      - contain-element: {match-regexp: "[Gg]oss"}
```

--------------------------------

### Validate Service State with Goss

Source: https://github.com/goss-org/goss/blob/master/docs/gossfile.md

Defines the expected state of a service like sshd. Ensures it is enabled and running, with optional runlevel configuration. Note that this checks the service manager's status, not the process's liveness.

```yaml
service:
  sshd:
    # Optional attributes
    # defaults to hash key
    name: sshd
    enabled: true
    running: true
    runlevels: ["3", "4", "5"]  # Alpine example, runlevels: ["default"]
    skip: false
```

--------------------------------

### Validate System with Nagios Format and Performance Data

Source: https://github.com/goss-org/goss/blob/master/docs/cli.md

Runs goss validation with the Nagios output format, including verbose details and performance data. This format is suitable for monitoring systems like Nagios or Sensu.

```console
$ 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 $?
```

--------------------------------

### Enable dgoss Debug Output

Source: https://github.com/goss-org/goss/blob/master/extras/dgoss/README.md

Set the DEBUG environment variable to 'true' to enable debug output from the dgoss script. The temporary directory will not be cleaned up in debug mode.

```bash
DEBUG=true dgoss run jenkins:alpine
```

--------------------------------

### Set Temporary Directory for dgoss

Source: https://github.com/goss-org/goss/blob/master/extras/dgoss/README.md

Customize the temporary directory used by dgoss by setting DGOSS_TEMP_DIR. The default is a dynamically created temporary directory.

```bash
export DGOSS_TEMP_DIR=/my/custom/tmp
```

--------------------------------

### Goss Validation Output (Incorrect File)

Source: https://github.com/goss-org/goss/blob/master/docs/gossfile.md

Console output from validating the incorrect goss file, showing only the second 'file' test was run.

```console
$ goss validate --format documentation
File: /var/www/html: exists: matches expectation: [true]
File: /var/www/html: filetype: matches expectation: ["directory"]
Service: httpd: enabled: matches expectation: [true]
Service: httpd: running: matches expectation: [true]

Total Duration: 0.014s
Count: 8, Failed: 0, Skipped: 0
```

--------------------------------

### Validate Local Port Listening

Source: https://github.com/goss-org/goss/blob/master/docs/gossfile.md

Verifies if a local port is listening on a specific IP address and protocol (TCP, TCP6, UDP, UDP6). Goss may auto-detect the protocol; use `goss add port ..` for accurate detection.

```yaml
port:
  # {tcp,tcp6,udp,udp6}:port_num
  tcp:22:
    # required attributes
    listening: true
    # optional attributes
    # defaults to hash key
    port: 'tcp:22'
    ip:
    - 0.0.0.0
    skip: false
```

--------------------------------

### Validate Goss with External Vars

Source: https://github.com/goss-org/goss/blob/master/docs/gossfile.md

Use external tools like Ohai or Facter to provide variables for Goss validation. The output of these tools is piped to the --vars option.

```bash
goss --vars <(ohai) validate
```

```bash
goss --vars <(facter -j) validate
```

--------------------------------

### Debug goss test execution with custom wait options

Source: https://github.com/goss-org/goss/blob/master/extras/dcgoss/README.md

Run dcgoss in debug mode with extended goss wait options. This is useful for troubleshooting test execution by increasing timeouts and sleep intervals.

```bash
DEBUG=true GOSS_FILES_PATH=db GOSS_WAIT_OPTS="-r 60s -s 5s" dcgoss run db
```

--------------------------------

### Validate File Attributes and Content

Source: https://github.com/goss-org/goss/blob/master/docs/gossfile.md

Checks various attributes of files, directories, sockets, or symbolic links, including existence, permissions, size, owner, group, and content checksums (MD5, SHA256, SHA512). For symlinks, 'linked-to' verifies the target path.

```yaml
file:
  /etc/passwd:
    # required attributes
    exists: true
    # optional attributes
    # defaults to hash key
    path: /etc/passwd
    mode: "0644"
    size: 2118 # in bytes
    owner: root
    group: root
    filetype: file # file, symlink, directory, socket
    contents: [] # Check file content for these patterns
    md5: 7c9bb14b3bf178e82c00c2a4398c93cd # md5 checksum of file
    # A stronger checksum alternatives to md5 (recommended)
    sha256: 7f78ce27859049f725936f7b52c6e25d774012947d915e7b394402cfceb70c4c
    sha512: cb71b1940dc879a3688bd502846bff6316dd537bbe917484964fe0f098e9245d80958258dc3bd6297bf42d5bd978cbe2c03d077d4ed45b2b1ed9cd831ceb1bd0
  /etc/alternatives/mta:
    # required attributes
    exists: true
    # optional attributes
    filetype: symlink # file, symlink, directory, socket
    linked-to: /usr/sbin/sendmail.sendmail
    skip: false
```

--------------------------------

### Validate Network Interface

Source: https://github.com/goss-org/goss/blob/master/docs/gossfile.md

Ensures a network interface exists and optionally checks its IP addresses and MTU. The interface name defaults to the key.

```yaml
interface:
  eth0:
    # required attributes
    exists: true
    # optional attributes
    # defaults to hash key
    name: eth0
    addrs:
    - 172.17.0.2/16
    - fe80::42:acff:fe11:2/64
    mtu: 1500
```

--------------------------------

### Validate User State with Goss

Source: https://github.com/goss-org/goss/blob/master/docs/gossfile.md

Configures validation for a user's existence and properties. This check inspects the local /etc/passwd file and does not validate remote users like those from LDAP.

```yaml
user:
  nfsnobody:
    # required attributes
    exists: true
    # optional attributes
    # defaults to hash key
    username: nfsnobody
    uid: 65534
    gid: 65534
    groups:
    - nfsnobody
    home: /var/lib/nfs
    shell: /sbin/nologin
    skip: false
```

--------------------------------

### Validate Command Exit Status and Output

Source: https://github.com/goss-org/goss/blob/master/docs/gossfile.md

Verifies the exit status and standard output/error of a command. Useful with gjson for custom tests. The 'exec' attribute defaults to the hash key if not provided.

```yaml
command:
  'go version':
    # required attributes
    exit-status: 0
    # optional attributes
    # defaults to hash key
    exec: "go version"
    stdout:
    - go version go1.6 linux/amd64
    stderr: []
    timeout: 10000 # in milliseconds
    skip: false
```

--------------------------------

### Specify Container Log Output Location

Source: https://github.com/goss-org/goss/blob/master/extras/dgoss/README.md

Set CONTAINER_LOG_OUTPUT to a non-empty string to retain logs from the tested container. The default is an empty string, meaning logs are not retained.

```bash
export CONTAINER_LOG_OUTPUT=/tmp/container.log
```

--------------------------------

### Validate Content with Templates

Source: https://github.com/goss-org/goss/blob/master/docs/gossfile.md

Validates content against matchers, using Jinja2 templating to dynamically insert variables from a JSON file. This allows for flexible and data-driven validation.

```json
{
  "instance_count": 14,
  "failures": 3,
  "status": "FAIL"
}
```

```yaml+jinja
matching:
  check_instance_count: # Make sure there is at least one instance
    content: {{ .Vars.instance_count }}
    matches:
      gt: 0

  check_failure_count_from_all_instance: # expect no failures
    content: {{ .Vars.failures }}
    matches: 0

  check_status:
    content: {{ .Vars.status }}
    matches:
      - not: FAIL
```

--------------------------------

### Mount Goss Volume to Another Container

Source: https://github.com/goss-org/goss/blob/master/docs/container_image.md

Mounts the volume from a running Goss container to a new container, allowing Goss to be used within that new container.

```sh
docker run --rm -it --volumes-from goss --name weby nginx
```

--------------------------------

### Goss Package Uninstall Test

Source: https://github.com/goss-org/goss/blob/master/docs/gossfile.md

Manually edited YAML to test the uninstall scenario for a package.

```yaml
package:
  nginx:
    installed: false
```