From 6ef2eae488537eae782f3187cae2d2983330cb51 Mon Sep 17 00:00:00 2001 From: Deepa Kumaraswamy Date: Fri, 13 May 2022 19:55:49 +0530 Subject: [PATCH] doc review Signed-off-by: Deepa Kumaraswamy --- docs-chef-io/content/inspec/resources/host.md | 77 ++++++++++--------- 1 file changed, 39 insertions(+), 38 deletions(-) diff --git a/docs-chef-io/content/inspec/resources/host.md b/docs-chef-io/content/inspec/resources/host.md index bcfe4735e..b67d7ae15 100644 --- a/docs-chef-io/content/inspec/resources/host.md +++ b/docs-chef-io/content/inspec/resources/host.md @@ -11,21 +11,21 @@ platform = "os" parent = "inspec/resources/os" +++ -Use the `host` Chef 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. +Use the `host` Chef InSpec audit resource to test the specific host name and its availability. This test includes the internet protocols and ports on which the respective host name must be available. ## Availability ### Installation -This resource is distributed along with Chef InSpec itself. You can use it automatically. +The Chef InSpec distributes this resource. ### Version -This resource first became available in v1.0.0 of InSpec. +This resource is available from InSpec version 1.0. ## Syntax -A `host` resource block declares a host name, and then (depending on what is to be tested) a port and/or a protocol: +A `host` resource block declares a host name, a port, and a protocol. describe host('example.com', port: 80, protocol: 'tcp') do it { should be_reachable } @@ -33,27 +33,29 @@ A `host` resource block declares a host name, and then (depending on what is to 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:` is the Internet protocol: TCP (`protocol: 'tcp'`), UDP (`protocol: 'udp'` or ICMP (`protocol: 'icmp'`)) +> where +> +> - `host()` must specify a host name, a port number, and a protocol. +> - `example.com` is the host name. +> - `port` is the port number. +> - `protocol` is the internet protocol, TCP (`protocol: 'tcp'`), UDP (`protocol: 'udp'`), and ICMP (`protocol: 'icmp'`) ## Properties ### ipaddress -The `ipaddress` property returns the ipaddresses of the host. +The `ipaddress` property returns the IP addresses of the host. its('ipaddress') { should include '93.184.216.34' } ### ipv4_address + The `ipv4_address` property returns the IPv4 address of the host. its('ipv4_address') { should include '93.184.216.34' } ### ipv6_address + The `ipv6_address` property returns the IPv6 addresses of the host. its('ipv6_address') { should include '2404:6800:4009:82a::200e' } @@ -64,13 +66,13 @@ The `connection` property returns the connection string. its('connection') { should match /connection refused/ } -### `protocol` +### protocol -The `protocol` property returns the protocol that given host is using. +The `protocol` property returns the protocol the specified host uses. - its('protocol') { should eq 'tcp' } + its('protocol') { should eq 'TCP' } -### `socket`property returns the socket for the given host. +### socket property returns the socket value of the specified host its('socket') { should match /STATUS_OK/ } @@ -80,38 +82,49 @@ This Chef InSpec audit resource has the following special matchers. For a full l ### be_reachable -The `be_reachable` matcher tests if the host name is available: +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": +The `be_resolvable` matcher tests for host name resolution. For example, "resolvable to an IP address". it { should be_resolvable } - ## Examples -### Verify that host name is resolvable to specific IP address. +### Verify host name is resolvable to a specific IP address describe host('example.com') do its('ipaddress') { should include '93.184.216.34' } end +### Verify host name is resolvable to a specific IPv4 address + + describe host('example.com') do + its('ipv4_address') { should include '93.184.216.34' } + end + +### Verify host name is resolvable to a specific IPv6 address + + describe host('example.com') do + its('ipv6_address') { should include '2404:6800:4009:82a::200e' } + end + +### Verify a specific IP address can be resolved + + describe host('example.com') do + it { should be_resolvable } + its('ipaddress') { should include '93.184.216.34' } + end + ### 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 '93.184.216.34' } - end - ### Review the connection setup and socket contents when checking reachability describe host('example.com', port: 12345, protocol: 'tcp') do @@ -119,15 +132,3 @@ The `be_resolvable` matcher tests for host name resolution, i.e. "resolvable to its('connection') { should_not match /connection refused/ } its('socket') { should match /STATUS_OK/ } end - -### Verify host name is resolveable to specific IPv4 address. - - describe host('example.com') do - its('ipv4_address') { should include '93.184.216.34' } - end - -### Verify host name is resolveable to specific IPv6 address. - - describe host('example.com') do - its('ipv6_address') { should include '2404:6800:4009:82a::200e' } - end \ No newline at end of file