---
title: About the host Resource
---

# 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:

.. code-block:: ruby

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


## Matchers

This InSpec audit resource has the following matchers:

### be

<%= partial "/shared/matcher_be" %>

### 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 }

### cmp

<%= partial "/shared/matcher_cmp" %>

### eq

<%= partial "/shared/matcher_eq" %>

### include

<%= partial "/shared/matcher_include" %>

### ipaddress

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

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

### match

<%= partial "/shared/matcher_match" %>

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