Class: Puppet::Provider::AixObject

Inherits:
Puppet::Provider show all
Defined in:
lib/puppet/provider/aix_object.rb

Overview

Common code for AIX user/group providers.

Defined Under Namespace

Classes: MappedObject

Constant Summary

Constants inherited from Puppet::Provider

Confine

Constants included from Util

Util::ALNUM, Util::ALPHA, Util::AbsolutePathPosix, Util::AbsolutePathWindows, Util::DEFAULT_POSIX_MODE, Util::DEFAULT_WINDOWS_MODE, Util::ESCAPED, Util::HEX, Util::HttpProxy, Util::PUPPET_STACK_INSERTION_FRAME, Util::RESERVED, Util::RFC_3986_URI_REGEX, Util::UNRESERVED, Util::UNSAFE

Constants included from Util::POSIX

Util::POSIX::LOCALE_ENV_VARS, Util::POSIX::USER_ENV_VARS

Constants included from Util::SymbolicFileMode

Util::SymbolicFileMode::SetGIDBit, Util::SymbolicFileMode::SetUIDBit, Util::SymbolicFileMode::StickyBit, Util::SymbolicFileMode::SymbolicMode, Util::SymbolicFileMode::SymbolicSpecialToBit

Constants included from Util::Docs

Util::Docs::HEADER_LEVELS

Instance Attribute Summary

Attributes inherited from Puppet::Provider

#resource

Attributes included from Util::Docs

#doc, #nodoc

Class Method Summary collapse

Instance Method Summary collapse

Methods inherited from Puppet::Provider

#<=>, #clear, command, #command, commands, declared_feature?, default?, default_match, defaultfor, execpipe, #execpipe, execute, #execute, fact_match, feature_match, #flush, has_command, #initialize, initvars, #inspect, #name, notdefaultfor, optional_commands, post_resource_eval, prefetch, some_default_match, specificity, supports_parameter?, #to_s

Methods included from Util::Logging

#clear_deprecation_warnings, #debug, #deprecation_warning, #format_backtrace, #format_exception, #get_deprecation_offender, #log_and_raise, #log_deprecations_to_file, #log_exception, #puppet_deprecation_warning, #send_log, setup_facter_logging!, #warn_once

Methods included from Util

absolute_path?, benchmark, chuser, clear_environment, create_erb, default_env, deterministic_rand, deterministic_rand_int, exit_on_fail, format_backtrace_array, format_puppetstack_frame, get_env, get_environment, logmethods, merge_environment, path_to_uri, pretty_backtrace, replace_file, resolve_stackframe, rfc2396_escape, safe_posix_fork, set_env, skip_external_facts, symbolizehash, thinmark, uri_encode, uri_query_encode, uri_to_path, uri_unescape, which, withenv, withumask

Methods included from Util::POSIX

#get_posix_field, #gid, groups_of, #idfield, #methodbyid, #methodbyname, #search_posix_field, #uid

Methods included from Util::SymbolicFileMode

#display_mode, #normalize_symbolic_mode, #symbolic_mode_to_int, #valid_symbolic_mode?

Methods included from Util::Docs

#desc, #dochook, #doctable, #markdown_definitionlist, #markdown_header, #nodoc?, #pad, scrub

Methods included from Util::Warnings

clear_warnings, debug_once, maybe_log, notice_once, warnonce

Methods included from Confiner

#confine, #confine_collection, #suitable?

Methods included from Util::Errors

#adderrorcontext, #devfail, #error_context, error_location, error_location_with_space, error_location_with_unknowns, #exceptwrap, #fail

Constructor Details

This class inherits a constructor from Puppet::Provider

Class Method Details

.instances ⇒ Object

Provider API



292
293
294
295
296
 
# File 'lib/puppet/provider/aix_object.rb', line 292

def instances
  list_all.to_a.map! do |object|
    new({ :name => object[:name] })
  end
end

.list_all(ia_module_args = []) ⇒ Object

Lists all instances of the given object, taking in an optional set of ia_module arguments. Returns an array of hashes, each hash having the schema

{
  :name => <object_name>
  :id   => <object_id>
}



278
279
280
281
282
283
284
285
286
 
# File 'lib/puppet/provider/aix_object.rb', line 278

def list_all(ia_module_args = [])
  cmd = [command(:list), '-c', *ia_module_args, '-a', 'id', 'ALL']
  parse_aix_objects(execute(cmd)).to_a.map do |object|
    name = object[:name]
    id = object[:attributes].delete(:id)

    { name: name, id: id }
  end
end

.mapping(info = {}) ⇒ Object

Add a mapping from a Puppet property to an AIX attribute. The info must include:

* :puppet_property       -- The puppet property corresponding to this attribute
* :aix_attribute         -- The AIX attribute corresponding to this attribute. Defaults
                         to puppet_property if this is not provided.
* :property_to_attribute -- A lambda that converts a Puppet Property to an AIX attribute
                         value. Defaults to the identity function if not provided.
* :attribute_to_property -- A lambda that converts an AIX attribute to a Puppet property.
                         Defaults to the identity function if not provided.

NOTE: The lambdas for :property_to_attribute or :attribute_to_property can be ‘pure’ or ‘impure’. A ‘pure’ lambda is one that needs only the value to do the conversion, while an ‘impure’ lambda is one that requires the provider instance along with the value. ‘Pure’ lambdas have the interface ‘do |value| …’ while ‘impure’ lambdas have the interface ‘do |provider, value| …’.

NOTE: ‘Impure’ lambdas are useful in case we need to generate more specific error messages or pass-in instance-specific command-line arguments.



97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
 
# File 'lib/puppet/provider/aix_object.rb', line 97

def mapping(info = {})
  identity_fn = ->(x) { x }
  info[:aix_attribute] ||= info[:puppet_property]
  info[:property_to_attribute] ||= identity_fn
  info[:attribute_to_property] ||= identity_fn

  mappings[:aix_attribute][info[:puppet_property]] = MappedObject.new(
    info[:aix_attribute],
    :convert_property_value,
    info[:property_to_attribute]
  )
  mappings[:puppet_property][info[:aix_attribute]] = MappedObject.new(
    info[:puppet_property],
    :convert_attribute_value,
    info[:attribute_to_property]
  )
end

.mappings ⇒ Object

Mappings



69
70
71
72
73
74
75
76
77
 
# File 'lib/puppet/provider/aix_object.rb', line 69

def mappings
  return @mappings if @mappings

  @mappings = {}
  @mappings[:aix_attribute] = {}
  @mappings[:puppet_property] = {}

  @mappings
end

.mk_resource_methods ⇒ Object

Defines the getter and setter methods for each Puppet property that’s mapped to an AIX attribute. We define only a getter for the :attributes property.

Provider subclasses should call this method after they’ve defined all of their <puppet_property> => <aix_attribute> mappings.



150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
 
# File 'lib/puppet/provider/aix_object.rb', line 150

def mk_resource_methods
  # Define the Getter methods for each of our properties + the attributes
  # property
  properties = [:attributes]
  properties += mappings[:aix_attribute].keys
  properties.each do |property|
    # Define the getter
    define_method(property) do
      get(property)
    end

    # We have a custom setter for the :attributes property,
    # so no need to define it.
    next if property == :attributes

    # Define the setter
    define_method("#{property}=".to_sym) do |value|
      set(property, value)
    end
  end
end

.numeric_mapping(info = {}) ⇒ Object

Creates a mapping from a purely numeric Puppet property to an attribute



117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
 
# File 'lib/puppet/provider/aix_object.rb', line 117

def numeric_mapping(info = {})
  property = info[:puppet_property]

  # We have this validation here b/c not all numeric properties
  # handle this at the property level (e.g. like the UID). Given
  # that, we might as well go ahead and do this validation for all
  # of our numeric properties. Doesn't hurt.
  info[:property_to_attribute] = lambda do |value|
    unless value.is_a?(Integer)
      raise ArgumentError, _("Invalid value %{value}: %{property} must be an Integer!") % { value: value, property: property }
    end

    value.to_s
  end

  # AIX will do the right validation to ensure numeric attributes
  # can't be set to non-numeric values, so no need for the extra clutter.
  info[:attribute_to_property] = lambda do |value|
    value.to_i
  end

  mapping(info)
end

.parse_aix_objects(output) ⇒ Object

Parses the AIX objects from the command output, returning an array of hashes with each hash having the following schema:

{
  :name       => <object_name>
  :attributes => <object_attributes>
}

Output should be of the form

#name:<attr1>:<attr2> ...
<name>:<value1>:<value2> ...
#name:<attr1>:<attr2> ...
<name>:<value1>:<value2> ...

NOTE: We need to parse the colon-formatted output in case we have space-separated attributes (e.g. ‘gecos’). “:” characters are escaped with a “#!”.



245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
 
# File 'lib/puppet/provider/aix_object.rb', line 245

def parse_aix_objects(output)
  # Object names cannot begin with '#', so we are safe to
  # split individual users this way. We do not have to worry
  # about an empty list either since there is guaranteed to be
  # at least one instance of an AIX object (e.g. at least one
  # user or one group on the system).
  _, *objects = output.chomp.split(/^#/)

  objects.map! do |object|
    attributes_line, values_line = object.chomp.split("\n")

    attributes = parse_colon_separated_list(attributes_line.chomp)
    attributes.map!(&:to_sym)

    values = parse_colon_separated_list(values_line.chomp)

    attributes_hash = attributes.zip(values).to_h

    object_name = attributes_hash.delete(:name)

    [[:name, object_name.to_s], [:attributes, attributes_hash]].to_h
  end

  objects
end

.parse_colon_separated_list(colon_list) ⇒ Object

Parses a colon-separated list. Example includes something like:

<item1>:<item2>:<item3>:<item4>

Returns an array of the parsed items, e.g.

[ <item1>, <item2>, <item3>, <item4> ]

Note that colons inside items are escaped by #!



200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
 
# File 'lib/puppet/provider/aix_object.rb', line 200

def parse_colon_separated_list(colon_list)
  # ALGORITHM:
  # Treat the colon_list as a list separated by '#!:' We will get
  # something like:
  #     [ <chunk1>, <chunk2>, ... <chunkn> ]
  #
  # Each chunk is now a list separated by ':' and none of the items
  # in each chunk contains an escaped ':'. Now, split each chunk on
  # ':' to get:
  #     [ [<piece11>, ..., <piece1n>], [<piece21>, ..., <piece2n], ... ]
  #
  # Now note that <item1> = <piece11>, <item2> = <piece12> in our original
  # list, and that <itemn> = <piece1n>#!:<piece21>. This is the main idea
  # behind what our inject method is trying to do at the end, except that
  # we replace '#!:' with ':' since the colons are no longer escaped.
  chunks = split_list(colon_list, '#!:')
  chunks.map! { |chunk| split_list(chunk, ':') }

  chunks.inject do |accum, chunk|
    left = accum.pop
    right = chunk.shift

    accum.push("#{left}:#{right}")
    accum += chunk

    accum
  end
end

.split_list(list, sep) ⇒ Object

This helper splits a list separated by sep into its corresponding items. Note that a key precondition here is that none of the items in the list contain sep.

Let A be the return value. Then one of our postconditions is:

A.join(sep) == list

NOTE: This function is only used by the parse_colon_separated_list function below. It is meant to be an inner lambda. The reason it isn’t here is so we avoid having to create a proc. object for the split_list lambda each time parse_colon_separated_list is invoked. This will happen quite often since it is used at the class level and at the instance level. Since this function is meant to be an inner lambda and thus not exposed anywhere else, we do not have any unit tests for it. These test cases are instead covered by the unit tests for parse_colon_separated_list



187
188
189
190
191
 
# File 'lib/puppet/provider/aix_object.rb', line 187

def split_list(list, sep)
  return [""] if list.empty?

  list.split(sep, -1)
end

Instance Method Details

#addcmd(attributes) ⇒ Object 



346
347
348
349
 
# File 'lib/puppet/provider/aix_object.rb', line 346

def addcmd(attributes)
  attribute_args = attributes_to_args(attributes)
  [self.class.command(:add)] + ia_module_args + attribute_args + [@resource[:name]]
end

#attributes=(new_attributes) ⇒ Object

Modifies the attribute property. Note we raise an error if the user specified an AIX attribute corresponding to a Puppet property.



413
414
415
416
417
418
 
# File 'lib/puppet/provider/aix_object.rb', line 413

def attributes=(new_attributes)
  validate_new_attributes(new_attributes)
  modify_object(new_attributes)
rescue Puppet::ExecutionFailure => detail
  raise Puppet::Error, _("Could not set attributes on %{resource}[%{name}]: %{detail}") % { resource: @resource.class.name, name: @resource.name, detail: detail }, detail.backtrace
end

#attributes_to_args(attributes) ⇒ Object

Converts the given attributes hash to CLI args.



328
329
330
331
332
 
# File 'lib/puppet/provider/aix_object.rb', line 328

def attributes_to_args(attributes)
  attributes.map do |attribute, value|
    "#{attribute}=#{value}"
  end
end

#create ⇒ Object

Creates a new instance of the resource



464
465
466
467
468
469
470
471
472
473
474
475
476
477
478
 
# File 'lib/puppet/provider/aix_object.rb', line 464

def create
  attributes = @resource.should(:attributes) || {}
  validate_new_attributes(attributes)

  mappings[:aix_attribute].each do |property, aix_attribute|
    property_should = @resource.should(property)
    next if property_should.nil?

    attributes[aix_attribute.name] = aix_attribute.convert_property_value(property_should)
  end

  execute(addcmd(attributes))
rescue Puppet::ExecutionFailure => detail
  raise Puppet::Error, _("Could not create %{resource} %{name}: %{detail}") % { resource: @resource.class.name, name: @resource.name, detail: detail }, detail.backtrace
end

#delete ⇒ Object

Deletes this instance resource



481
482
483
484
485
486
487
488
489
490
 
# File 'lib/puppet/provider/aix_object.rb', line 481

def delete
  execute(deletecmd)

  # Recollect the object info so that our current properties reflect
  # the actual state of the system. Otherwise, puppet resource reports
  # the wrong info. at the end. Note that this should return nil.
  object_info(true)
rescue Puppet::ExecutionFailure => detail
  raise Puppet::Error, _("Could not delete %{resource} %{name}: %{detail}") % { resource: @resource.class.name, name: @resource.name, detail: detail }, detail.backtrace
end

#deletecmd ⇒ Object 



351
352
353
 
# File 'lib/puppet/provider/aix_object.rb', line 351

def deletecmd
  [self.class.command(:delete)] + ia_module_args + [@resource[:name]]
end

#exists? ⇒ Boolean

Check that the AIX object exists

Returns:

  • (Boolean) 


459
460
461
 
# File 'lib/puppet/provider/aix_object.rb', line 459

def exists?
  !object_info.nil?
end

#get(property) ⇒ Object

Gets a Puppet property’s value from object_info



367
368
369
370
371
 
# File 'lib/puppet/provider/aix_object.rb', line 367

def get(property)
  return :absent unless exists?

  object_info[property] || :absent
end

#ia_module_args ⇒ Object

Raises:

  • (ArgumentError) 


334
335
336
337
338
339
340
 
# File 'lib/puppet/provider/aix_object.rb', line 334

def ia_module_args
  raise ArgumentError, _("Cannot have both 'forcelocal' and 'ia_load_module' at the same time!") if @resource[:ia_load_module] && @resource[:forcelocal]
  return ["-R", @resource[:ia_load_module].to_s] if @resource[:ia_load_module]
  return ["-R", "files"] if @resource[:forcelocal]

  []
end

#lscmd ⇒ Object 



342
343
344
 
# File 'lib/puppet/provider/aix_object.rb', line 342

def lscmd
  [self.class.command(:list), '-c'] + ia_module_args + [@resource[:name]]
end

#mappings ⇒ Object

Instantiate our mappings. These need to be at the instance-level since some of our mapped objects may have impure conversion functions that need our provider instance.



302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
 
# File 'lib/puppet/provider/aix_object.rb', line 302

def mappings
  return @mappings if @mappings

  @mappings = {}
  self.class.mappings.each do |type, mapped_objects|
    @mappings[type] = {}
    mapped_objects.each do |input, mapped_object|
      if mapped_object.pure_conversion_fn?
        # Our mapped_object has a pure conversion function so we
        # can go ahead and use it as-is.
        @mappings[type][input] = mapped_object
        next
      end

      # Otherwise, we need to dup it and set its provider to our
      # provider instance. The dup is necessary so that we do not
      # touch the class-level mapped object.
      @mappings[type][input] = mapped_object.dup
      @mappings[type][input].set_provider(self)
    end
  end

  @mappings
end

#modify_object(new_attributes) ⇒ Object

Modifies the AIX object by setting its new attributes.



361
362
363
364
 
# File 'lib/puppet/provider/aix_object.rb', line 361

def modify_object(new_attributes)
  execute(modifycmd(new_attributes))
  object_info(true)
end

#modifycmd(new_attributes) ⇒ Object 



355
356
357
358
 
# File 'lib/puppet/provider/aix_object.rb', line 355

def modifycmd(new_attributes)
  attribute_args = attributes_to_args(new_attributes)
  [self.class.command(:modify)] + ia_module_args + attribute_args + [@resource[:name]]
end

#object_info(refresh = false) ⇒ Object

Collects the current property values of all mapped properties + the attributes property.



422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
 
# File 'lib/puppet/provider/aix_object.rb', line 422

def object_info(refresh = false)
  return @object_info if @object_info && !refresh

  @object_info = nil

  begin
    output = execute(lscmd)
  rescue Puppet::ExecutionFailure
    Puppet.debug(_("aix.object_info(): Could not find %{resource}[%{name}]") % { resource: @resource.class.name, name: @resource.name })

    return @object_info
  end

  # If lscmd succeeds, then output will contain our object's information.
  # Thus, .parse_aix_objects will always return a single element array.
  aix_attributes = self.class.parse_aix_objects(output).first[:attributes]
  aix_attributes.each do |attribute, value|
    @object_info ||= {}

    # If our attribute has a Puppet property, then we store that. Else, we store it as part
    # of our :attributes property hash
    if (property = mappings[:puppet_property][attribute])
      @object_info[property.name] = property.convert_attribute_value(value)
    else
      @object_info[:attributes] ||= {}
      @object_info[:attributes][attribute] = value
    end
  end

  @object_info
end

#set(property, value) ⇒ Object

Sets a mapped Puppet property’s value.



374
375
376
377
378
379
380
381
 
# File 'lib/puppet/provider/aix_object.rb', line 374

def set(property, value)
  aix_attribute = mappings[:aix_attribute][property]
  modify_object(
    { aix_attribute.name => aix_attribute.convert_property_value(value) }
  )
rescue Puppet::ExecutionFailure => detail
  raise Puppet::Error, _("Could not set %{property} on %{resource}[%{name}]: %{detail}") % { property: property, resource: @resource.class.name, name: @resource.name, detail: detail }, detail.backtrace
end

#validate_new_attributes(new_attributes) ⇒ Object

This routine validates our new attributes property value to ensure that it does not contain any Puppet properties.

Raises:



385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
 
# File 'lib/puppet/provider/aix_object.rb', line 385

def validate_new_attributes(new_attributes)
  # Gather all of the <puppet property>, <aix attribute> conflicts to print
  # them all out when we create our error message. This makes it easy for the
  # user to update their manifest based on our error message.
  conflicts = {}
  mappings[:aix_attribute].each do |property, aix_attribute|
    next unless new_attributes.key?(aix_attribute.name)

    conflicts[:properties] ||= []
    conflicts[:properties].push(property)

    conflicts[:attributes] ||= []
    conflicts[:attributes].push(aix_attribute.name)
  end

  return if conflicts.empty?

  properties, attributes = conflicts.keys.map do |key|
    conflicts[key].map! { |name| "'#{name}'" }.join(', ')
  end

  detail = _("attributes is setting the %{properties} properties via. the %{attributes} attributes, respectively! Please specify these property values in the resource declaration instead.") % { properties: properties, attributes: attributes }

  raise Puppet::Error, _("Could not set attributes on %{resource}[%{name}]: %{detail}") % { resource: @resource.class.name, name: @resource.name, detail: detail }
end