About Ohai

[edit on GitHub]

Ohai is a tool that is used to collect system configuration data, which is provided to Chef Infra Client for use within cookbooks. Ohai is run by Chef Infra Client at the beginning of every Chef run to determine system state. Ohai includes many built-in plugins to detect common configuration details as well as a plugin model for writing custom plugins.

The types of attributes Ohai collects include but are not limited to:

  • Operating System
  • Network
  • Memory
  • Disk
  • CPU
  • Kernel
  • Host names
  • Fully qualified domain names
  • Virtualization
  • Cloud provider metadata

Attributes that are collected by Ohai are automatic level attributes, in that these attributes are used by Chef Infra Client to ensure that these attributes remain unchanged after Chef Infra Client is done configuring the node.

Ohai collects data for many platforms, including AIX, Darwin, Linux, FreeBSD, OpenBSD, NetBSD, Solaris, and any Microsoft Windows operating systems.

See the Chef Infra Client release notes for the latest information on Ohai.

Automatic Attributes

An automatic attribute is a specific detail about a node, such as an IP address, a host name, a list of loaded kernel modules, and so on. Automatic attributes are detected by Ohai and are then used by Chef Infra Client to ensure that they are handled properly during every Chef Infra Client run. The most commonly accessed automatic attributes are:

Attribute Description
node['platform'] The platform on which a node is running. This attribute helps determine which providers will be used.
node['platform_family'] The platform family is a Chef Infra specific grouping of similar platforms where cookbook code can often be shared. For example `rhel` includes Red Hat Linux, Oracle Linux, CentOS, and several other platforms that are nearly identical to Red Hat Linux.
node['platform_version'] The version of the platform. This attribute helps determine which providers will be used.
node['ipaddress'] The IP address for a node. If the node has a default route, this is the IPV4 address for the interface. If the node does not have a default route, the value for this attribute should be nil. The IP address for default route is the recommended default value.
node['macaddress'] The MAC address for a node, determined by the same interface that detects the node['ipaddress'].
node['fqdn'] The fully qualified domain name for a node. This is used as the name of a node unless otherwise set.
node['hostname'] The host name for the node.
node['domain'] The domain for the node.
node['recipes'] A list of recipes associated with a node (and part of that node's run-list).
node['roles'] A list of roles associated with a node (and part of that node's run-list).
node['ohai_time'] The time at which Ohai was last run. This attribute is not commonly used in recipes, but it is saved to the Chef Infra Server and can be accessed using the knife status subcommand.

Get a list of automatic attributes for a node

Ohai collects a list of automatic attributes at the start of each Chef Infra Client run. This list will vary from organization to organization, by server type, and by the platform that runs those servers. All the attributes collected by Ohai are unmodifiable by Chef Infra Client. Run the ohai command on a system to see which automatic attributes Ohai has collected for a particular node.

Note

Attributes can be configured in cookbooks (attribute files and recipes), roles, and environments. In addition, Ohai collects attribute data about each node at the start of a Chef Infra Client run. See Attributes for more information about how all of these attributes fit together.

Attributes Blocklist

Warning

When attribute blocklist settings are used, any attribute defined in a blocklist will not be saved to the Chef Infra Server and any attribute that is not defined in a blocklist will be saved. Each attribute type must be blocklisted independently of the other attribute types. For example, if blocked_automatic_attributes defines attributes that will not be saved, but blocked_normal_attributes, blocked_default_attributes, and blocked_override_attributes are not defined, then all normal attributes, default attributes, and override attributes will be saved, as well as the automatic attributes that were not specifically excluded through blocklisting.

Attributes that should not be saved by a node may be blocklisted in the client.rb file. The blocklist is a Hash of keys that specify each attribute to be filtered out.

Attributes are blocklisted by attribute type, with each attribute type being blocklisted independently. Each attribute type—automatic, default, normal, and override—may define blocklists by using the following settings in the client.rb file:

Setting Description
blocked_automatic_attributes A hash that blocklists automatic attributes, preventing blocklisted attributes from being saved. For example: ['network/interfaces/eth0']. Default value: nil, all attributes are saved. If the array is empty, all attributes are saved.
blocked_default_attributes A hash that blocklists default attributes, preventing blocklisted attributes from being saved. For example: ['filesystem/dev/disk0s2/size']. Default value: nil, all attributes are saved. If the array is empty, all attributes are saved.
blocked_normal_attributes A hash that blocklists normal attributes, preventing blocklisted attributes from being saved. For example: ['filesystem/dev/disk0s2/size']. Default value: nil, all attributes are saved. If the array is empty, all attributes are saved.
blocked_override_attributes A hash that blocklists override attributes, preventing blocklisted attributes from being saved. For example: ['map - autohome/size']. Default value: nil, all attributes are saved. If the array is empty, all attributes are saved.

Blocklisting Ohai (automatic) Attributes

The recommended practice is to use blocked_automatic_attributes to block attributes populated by Ohai’s system information gathering. Ohai gathers a large number of attributes that can consume a signicant amount of storage space on the Chef Infra Server. Many of these attributes may be considered highly valuable, while others could be blocklisted without any impact to data available in search. Normal, default, and override attributes are typically much more important attributes used within cookbooks and are more likely to cause issues if they are blocklisted incorrectly.

For example, automatic attribute data similar to:

{
  "filesystem" => {
    "/dev/disk0s2" => {
      "size" => "10mb"
    },
    "map - autohome" => {
      "size" => "10mb"
    }
  },
  "network" => {
    "interfaces" => {
      "eth0" => {...},
      "eth1" => {...},
    }
  }
}

To blocklist the filesystem attributes and allow the other attributes to be saved, update the client.rb file:

blocked_automatic_attributes ['filesystem']

When a blocklist is defined, any attribute of that type that is not specified in that attribute blocklist will be saved. So based on the previous blocklist for automatic attributes, the filesystem and map - autohome attributes will not be saved, but the network attributes will.

For attributes that contain slashes (/) within the attribute value, such as the filesystem attribute '/dev/diskos2', use an array. For

example:

blocked_automatic_attributes [['filesystem', '/dev/diskos2']]

Attribute Allowlist

Warning

When attribute allowlist settings are used, only the attributes defined in a allowlist will be saved and any attribute that is not defined in a allowlist will not be saved. Each attribute type is allowlisted independently of the other attribute types. For example, if automatic_attribute_allowlist defines attributes to be saved, but normal_attribute_allowlist, default_attribute_allowlist, and override_attribute_allowlist are not defined, then all normal attributes, default attributes, and override attributes are saved, as well as the automatic attributes that were specifically included through allowlisting.

Attributes that should be saved by a node may be allowlisted in the client.rb file. The allowlist is a hash of keys that specifies each attribute to be saved.

Attributes are allowlisted by attribute type, with each attribute type being allowlisted independently. Each attribute type—automatic, default, normal, and override—may define allowlists by using the following settings in the client.rb file:

Setting Description
allowed_automatic_attributes A hash that allowlists automatic attributes, preventing non-allowlisted attributes from being saved. For example: ['network/interfaces/eth0']. Default value: nil, all attributes are saved. If the hash is empty, no attributes are saved.
allowed_default_attributes A hash that allowlists default attributes, preventing non-allowlisted attributes from being saved. For example: ['filesystem/dev/disk0s2/size']. Default value: nil, all attributes are saved. If the hash is empty, no attributes are saved.
allowed_normal_attributes A hash that allowlists normal attributes, preventing non-allowlisted attributes from being saved. For example: ['filesystem/dev/disk0s2/size']. Default value: nil, all attributes are saved. If the hash is empty, no attributes are saved.
allowed_override_attributes A hash that allowlists override attributes, preventing non-allowlisted attributes from being saved. For example: ['map - autohome/size']. Default value: nil, all attributes are saved. If the hash is empty, no attributes are saved.

Allowlisting Ohai (automatic) Attributes

The recommended practice is to use allowed_automatic_attributes to allow specific attributes populated by Ohai’s system information gathering. Ohai gathers a large number of attributes that can consume a signicant amount of storage space on the Chef Infra Server. Many of these attributes may be considered highly valuable, while others could be skipped without any impact to data available in search. Normal, default, and override attributes are typically much more important attributes used within cookbooks and are more likely to cause issues if they are ommited from an allowlist incorrectly.

For example, automatic attribute data similar to:

{
  "filesystem" => {
    "/dev/disk0s2" => {
      "size" => "10mb"
    },
    "map - autohome" => {
      "size" => "10mb"
    }
  },
  "network" => {
    "interfaces" => {
      "eth0" => {...},
      "eth1" => {...},
    }
  }
}

To allowlist the network attributes and prevent the other attributes from being saved, update the client.rb file:

allowed_automatic_attributes ['network/interfaces/']

When a allowlist is defined, any attribute of that type that is not specified in that attribute allowlist will not be saved. So based on the previous allowlist for automatic attributes, the filesystem and map - autohome attributes will not be saved, but the network attributes will.

Leave the value empty to prevent all attributes of that attribute type from being saved:

allowed_automatic_attributes []

For attributes that contain slashes (/) within the attribute value, such as the filesystem attribute '/dev/diskos2', use an array. For example:

allowed_automatic_attributes [['filesystem', '/dev/diskos2']]

Default Plugins

The following list shows the type of plugins that are included with Ohai. See the ohai/lib/ohai/plugins directory in the version of Ohai installed on your system for the full list:

General Purpose Plugins

azure.rb
c.rb
chef.rb
cloud.rb
command.rb
cpu.rb
digital_ocean.rb
dmi.rb
docker.rb
ec2.rb
elixir.rb
erlang.rb
eucalyptus.rb
filesystem.rb
freebsd
gce.rb
go.rb
groovy.rb
haskell.rb
hostname.rb
init_package.rb
java.rb
joyent.rb
kernel.rb
keys.rb
languages.rb
libvirt.rb
linode.rb
lua.rb
mono.rb
network.rb
nodejs.rb
ohai_time.rb
ohai.rb
memory.rb
network.rb
platform.rb
openstack.rb
os.rb
packages.rb
perl.rb
php.rb
platform.rb
powershell.rb
ps.rb
python.rb
rackspace.rb
root_group.rb
ruby.rb
rust.rb
scala.rb
scaleway.rb
shard.rb
shells.rb
softlayer.rb
ssh_host_key.rb
timezone.rb
uptime.rb
virtualbox.rb
vmware.rb
zpools.rb

Platform Specific Plugins

aix
  kernel.rb
  memory.rb
  network.rb
  platform.rb
  uptime.rb
  virtualization.rb
bsd
 virtualization.rb
darwin
  cpu.rb
  filesystem.rb
  hardware.rb
  memory.rb
  network.rb
  platform.rb
  system_profiler.rb
  virtualization.rb
dragonflybsd
 cpu.rb
 memory.rb
 network.rb
 os.rb
 platform.rb
freebsd
  cpu.rb
  memory.rb
  network.rb
  os.rb
  platform.rb
linux
  block_device.rb
  cpu.rb
  filesystem.rb
  fips.rb
  hostnamectl.rb
  lsb.rb
  machineid.rb
  mdadm.rb
  memory.rb
  network.rb
  platform.rb
  sessions.rb
  virtualization.rb
netbsd
  cpu.rb
  memory.rb
  network.rb
  platform.rb
openbsd
  cpu.rb
  memory.rb
  network.rb
  platform.rb
solaris2
  cpu.rb
  dmi.rb
  filesystem.rb
  memory.rb
  network.rb
  platform.rb
  virtualization.rb
windows
  cpu.rb
  drivers.rb
  filesystem.rb
  fips.rb
  memory.rb
  network.rb
  platform.rb
  system_enclosure.rb
  virtualization.rb

Optional Plugins

Ohai ships several plugins that are considered optional and can be enabled in the client.rb configuration file.

  • :IPC - SysV IPC shmem information (New in Chef Infra Client 16)
  • :Interupts - Data from /proc/interrupts and /proc/irq (New in Chef Infra Client 16)
  • :Lspci - PCI device information on Linux hosts.
  • :Lsscsi - SCSI device information on Linux hosts.
  • :Passwd - User and Group information on non-Windows hosts. This plugin can result in very large node sizes if a system connects to Active Directory or LDAP.
  • :Sessions - Sessions data from loginctl on Linux hosts.
  • :Sysctl - All sysctl values on Linux hosts.

Enabling Optional Plugins

Optional plugins can be enabled in the client.rb configuration file:

ohai.optional_plugins = [
  :Sessions,
  :Lspci,
]

Note

The Ohai optional_plugins config array must contain an array of plugin names as Symbols not Strings.

Ohai Settings in client.rb

Ohai configuration settings can be added to the client.rb file.

ohai.directory

The directory in which Ohai plugins are located.

ohai.disabled_plugins

An array of Ohai plugins to be disabled on a node. The list of plugins included in Ohai can be found in the ohai/lib/ohai/plugins source. For example, disabling a single plugin:

ohai.disabled_plugins = [
  :MyPlugin
]

or disabling multiple plugins:

ohai.disabled_plugins = [
  :MyPlugin,
  :MyPlugin2,
  :MyPlugin3
]

When a plugin is disabled, the Chef Infra Client log file will contain entries similar to:

[2014-06-13T23:49:12+00:00] DEBUG: Skipping disabled plugin MyPlugin
ohai.hints_path

The path to the file that contains hints for Ohai.

ohai.log_level

The level of logging to be stored in a log file.

ohai.log_location

The location of the log file.

ohai.plugin_path

An array of paths at which Ohai plugins are located. Default value: [<CHEF_GEM_PATH>/ohai-9.9.9/lib/ohai/plugins]. When custom Ohai plugins are added, the paths must be added to the array. For example, a single plugin:

ohai.plugin_path << '/etc/chef/ohai_plugins'

and for multiple plugins:

ohai.plugin_path += [
  '/etc/chef/ohai_plugins',
  '/path/to/other/plugins'
  ]

Note

The Ohai executable ignores settings in the client.rb file when Ohai is run independently of Chef Infra Client.

Custom Plugins

Custom Ohai plugins can be written to collect additional information from systems as necessary. See the Ohai Custom Plugins docs for more information.

Hints

Ohai hints are used to tell Ohai something about the system that it is running on that it would not be able to discover itself. An Ohai hint exists if a JSON file exists in the hint directory with the same name as the hint. For example, calling hint?('antarctica') in an Ohai plugin would return an empty hash if the file antarctica.json existed in the hints directory, and return nil if the file does not exist.

If the hint file contains JSON content, it will be returned as a hash from the call to hint?.

{
  "snow": true,
  "penguins": "many"
}
antarctica_hint = hint?('antarctica')
if antarctica_hint['snow']
  "There are #{antarctica_hint['penguins']} penguins here."
else
  'There is no snow here, and penguins like snow.'
end

Hint files are located in the /etc/chef/ohai/hints/ directory by default. Use the Ohai.config[:hints_path] setting in the client.rb configuration file to customize this location.

ohai Cookbook Resource

Chef Infra Client includes an ohai resource that allows you to reload the Ohai data on a node. This allows recipes or resources that change system attributes (like a recipe that adds a user) to refer to those attributes later on during a Chef Infra Client run. See the ohai resource for complete usage information.

ohai Command Line Tool

Ohai can be run on the command line outside of the Chef Infra Client run. See Ohai (executable) for more information.

© Chef Software, Inc.
Licensed under the Creative Commons Attribution 3.0 Unported License.
The Chef™ Mark and Chef Logo are either registered trademarks/service marks or trademarks/servicemarks of Chef, in the United States and other countries and are used with Chef Inc's permission.
We are not affiliated with, endorsed or sponsored by Chef Inc.
https://docs.chef.io/ohai/