Core Resources

A resource is a single piece of state managed by OpenVox.

A file resource named hello_world:

file { 'hello_world': }

A very common resource pattern — install a package, create a configuration file, and restart a service when that file changes:

package {'ntp':} -> file {'/etc/ntp.conf':} ~> service {'ntpd':}

Resource type reference

Abstraction

Resources are the bottom layer of an abstraction model that runs from modules down to individual attributes:

graph TD
  subgraph Abstraction_Model
  a[Module]-->|One module to many classes|b[Class]
  b-->|One class to many resources|c[Resource]
  c-->|Resources are described by attributes|d[Attribute]
  end
  subgraph ntp_module
    e[ntp_module]-->f[classes in ntp module]
    f-->g[resources in ntp classes]
    g-->h[resource describing attributes]
  end

Resource syntax

resource-type { 'resource name':
  parameter => 'String value',
  parameter => [
    'Array value',
    'another value',
  ],
  parameter => {
    'Hash key' => 'Hash value',
  },
}

Warning

A given resource — the combination of resource-type and resource name — can only be defined once in a compiled catalog.

file

File resources manage files, directories, and symlinks on the filesystem.

Use ensure => file to manage files:

file { '/etc/resolv.conf':
  ensure  => file,
  owner   => 'root',
  group   => 'root',
  mode    => '0644',
  content => 'search example.com
nameserver 8.8.8.8',
}

Use ensure => directory to manage directories:

file { '/etc/facter':
  ensure => directory,
  owner  => 'root',
  group  => 'root',
  mode   => '0755',
}

Use ensure => link to manage symbolic links:

file { '/etc/localtime':
  ensure => link,
  target => '/usr/share/zoneinfo/US/Pacific',
}

file resource type

package

Installs or removes packages using the system's default package manager.

package { 'vim':
  ensure => installed,
}

package { 'emacs':
  ensure => absent,
}

package resource type

service

Manages services. ensure manages the running state of the service; enable manages whether it starts on boot.

service { 'sshd':
  ensure => running,
  enable => true,
}

service { 'xinetd':
  ensure => stopped,
  enable => false,
}

service resource type

group

Group resources manage groups.

group { 'mysql':
  ensure => present,
  gid    => '27',
}

group resource type

user

User resources manage users.

user { 'mysql':
  ensure     => present,
  comment    => 'MySQL Server',
  uid        => '27',
  gid        => 'mysql',
  home       => '/var/lib/mysql',
  managehome => false,
  shell      => '/sbin/nologin',
}

Listing groups in gid (the user's primary group) or groups (the user's supplemental groups) automatically creates dependencies on those group resources, if they exist.

user resource type

notify

Logs a message on the agent node.

notify { 'This is a non-fatal message.': }

notify resource type

Relationships and ordering

By default, resources are applied in the order they are declared in a manifest. OpenVox also supplies metaparameters to control ordering and dependent relationships explicitly.

Relationships and ordering

require and before

In this example, the configuration file requires that the package be installed:

package { 'ntp':
  ensure => present,
}

file { '/etc/ntp.conf':
  ensure  => file,
  require => Package['ntp'],
}

In this equivalent example, the package must be installed before the configuration file:

package { 'ntp':
  ensure => present,
  before => File['/etc/ntp.conf'],
}

file { '/etc/ntp.conf':
  ensure => file,
}

The Package[...] and File[...] used above are resource references.

Resource references

subscribe and notify

In this example, the service requires the configuration file to exist and will refresh (restart) if the file changes:

file { '/etc/ntp.conf':
  ensure => file,
}

service { 'ntpd':
  ensure    => running,
  enable    => true,
  subscribe => File['/etc/ntp.conf'],
}

In this equivalent example, the relationship is declared in the opposite direction:

file { '/etc/ntp.conf':
  ensure => file,
  notify => Service['ntpd'],
}

service { 'ntpd':
  ensure => running,
  enable => true,
}

Refreshing and notification

Chaining

Chaining arrows are shorthand for the relationship metaparameters:

• -> is equivalent to before
• ~> is equivalent to notify

A common pattern chains package, configuration file, and service resources:

package {'ntp':} -> file {'/etc/ntp.conf':} ~> service {'ntpd':}

Chaining arrows

exec

exec is used to run arbitrary commands.

file { ['/etc/facter','/etc/facter/facts.d']:
  ensure => directory,
  mode   => '0755',
}

file { '/etc/facter/facts.d/lastrun':
  content => '#!/bin/bash
stat -c "lastrun=%Y" "$0"',
  mode    => '0755',
}

exec { 'touch /etc/facter/facts.d/lastrun':
  path => '/bin:/usr/bin',
}

This example creates an external fact lastrun that gives the time of the last OpenVox run (in seconds since the epoch).

Try it yourself

Save the manifest above in a file and use puppet apply as root to apply it. Examine the output of repeated puppet apply runs and the value of facter lastrun.

Warning

The touch command above executes on every run. For many reasons, exec should be avoided when possible — and when it is necessary, exec resources should always be constrained with one of the parameters below.

exec resource type

creates

Commands that create files can be set to run only once by specifying the created file with creates. The exec runs only if the file named by creates does not exist.

exec { 'touch /tmp/runonce':
  path    => '/bin:/usr/bin',
  creates => '/tmp/runonce',
}

Try it yourself

Save the manifest above and apply it with puppet apply. Examine the output of repeated runs.

onlyif and unless

onlyif and unless test the return value of a command to decide whether to execute an exec resource. The following are equivalent:

exec { '/usr/local/bin/somescript':
  onlyif => '/bin/test -x /usr/local/bin/somescript',
}

exec { '/usr/local/bin/somescript':
  unless => '/bin/test ! -x /usr/local/bin/somescript',
}

refreshonly

Only run the exec on a subscribe or notify event. For example, the following runs newaliases when /etc/aliases is updated (assuming /etc/aliases is declared as a file resource):

exec { '/usr/bin/newaliases':
  refreshonly => true,
  subscribe   => File['/etc/aliases'],
}

Other core resources

These are part of the resource abstraction layer but are not commonly used:

• filebucket configures backup locations for OpenVox-modified files
• The resources meta-resource controls the behavior of other resources
• schedule controls when a manifest will apply
• stage can order the application of classes
• tidy cleans up files, similar to tmpwatch

Resource type reference