host

Use the host InSpec audit resource to test the name used to refer to a specific host and its availability, including the Internet protocols and ports over which that host name should be available.


Syntax

A host resource block declares a host name, and then (depending on what is to be tested) a port and/or a protocol:

describe host('example.com', port: 80, protocol: 'tcp') do
  it { should be_reachable }
  it { should be_resolvable }
  its('ipaddress') { should include '12.34.56.78' }
end

where

  • host() must specify a host name and may specify a port number and/or a protocol
  • 'example.com' is the host name
  • port: is the port number
  • protocol: 'name' is the Internet protocol: TCP (protocol: 'tcp'), UDP (protocol: 'udp' or ICMP (protocol: 'icmp'))


Examples

The following examples show how to use this InSpec audit resource.

Verify host name is reachable over a specific protocol and port number

describe host('example.com', port: 80, protocol: 'tcp') do
  it { should be_reachable }
end

Verify that a specific IP address can be resolved

describe host('example.com') do
  it { should be_resolvable }
  its('ipaddress') { should include '192.168.1.1' }
end

Review the connection setup and socket contents when checking reachability

describe host('example.com', port: 12345, protocol: 'tcp') do
  it { should be_reachable }
  its('connection') { should_not match /connection refused/ }
  its('socket') { should match /STATUS_OK/ }
end


Matchers

For a full list of available matchers, please visit our matchers page.

be_reachable

The be_reachable matcher tests if the host name is available:

it { should be_reachable }

be_resolvable

The be_resolvable matcher tests for host name resolution, i.e. “resolvable to an IP address”:

it { should be_resolvable }

ipaddress

The ipaddress matcher tests if a host name is resolvable to a specific IP address:

its('ipaddress') { should include '93.184.216.34' }