3rdparty/modules/stdlib/lib/puppet/type/file_line.rb

   1 Puppet::Type.newtype(:file_line) do
   2   desc <<-DOC
   3     Ensures that a given line is contained within a file.  The implementation
   4     matches the full line, including whitespace at the beginning and end.  If
   5     the line is not contained in the given file, Puppet will append the line to
   6     the end of the file to ensure the desired state.  Multiple resources may
   7     be declared to manage multiple lines in the same file.
   8
   9     Example:
  10
  11         file_line { 'sudo_rule':
  12           path => '/etc/sudoers',
  13           line => '%sudo ALL=(ALL) ALL',
  14         }
  15
  16         file_line { 'sudo_rule_nopw':
  17           path => '/etc/sudoers',
  18           line => '%sudonopw ALL=(ALL) NOPASSWD: ALL',
  19         }
  20
  21     In this example, Puppet will ensure both of the specified lines are
  22     contained in the file /etc/sudoers.
  23
  24     Match Example:
  25
  26         file_line { 'bashrc_proxy':
  27           ensure => present,
  28           path   => '/etc/bashrc',
  29           line   => 'export HTTP_PROXY=http://squid.puppetlabs.vm:3128',
  30           match  => '^export\ HTTP_PROXY\=',
  31         }
  32
  33     In this code example match will look for a line beginning with export
  34     followed by HTTP_PROXY and replace it with the value in line.
  35
  36     Examples With `ensure => absent`:
  37
  38     This type has two behaviors when `ensure => absent` is set.
  39
  40     One possibility is to set `match => ...` and `match_for_absence => true`,
  41     as in the following example:
  42
  43         file_line { 'bashrc_proxy':
  44           ensure            => absent,
  45           path              => '/etc/bashrc',
  46           match             => '^export\ HTTP_PROXY\=',
  47           match_for_absence => true,
  48         }
  49
  50     In this code example match will look for a line beginning with export
  51     followed by HTTP_PROXY and delete it.  If multiple lines match, an
  52     error will be raised unless the `multiple => true` parameter is set.
  53
  54     Note that the `line => ...` parameter would be accepted BUT IGNORED in
  55     the above example.
  56
  57     The second way of using `ensure => absent` is to specify a `line => ...`,
  58     and no match:
  59
  60         file_line { 'bashrc_proxy':
  61           ensure => absent,
  62           path   => '/etc/bashrc',
  63           line   => 'export HTTP_PROXY=http://squid.puppetlabs.vm:3128',
  64         }
  65
  66     Note that when ensuring lines are absent this way, the default behavior
  67     this time is to always remove all lines matching, and this behavior
  68     can't be disabled.
  69
  70     Encoding example:
  71
  72         file_line { "XScreenSaver":
  73           ensure   => present,
  74           path     => '/root/XScreenSaver',
  75           line     => "*lock: 10:00:00",
  76           match    => '^*lock:',
  77           encoding => "iso-8859-1",
  78         }
  79
  80     Files with special characters that are not valid UTF-8 will give the
  81     error message "invalid byte sequence in UTF-8".  In this case, determine
  82     the correct file encoding and specify the correct encoding using the
  83     encoding attribute, the value of which needs to be a valid Ruby character
  84     encoding.
  85
  86     **Autorequires:** If Puppet is managing the file that will contain the line
  87     being managed, the file_line resource will autorequire that file.
  88   DOC
  89
  90   ensurable do
  91     defaultvalues
  92     defaultto :present
  93   end
  94
  95   newparam(:name, :namevar => true) do
  96     desc 'An arbitrary name used as the identity of the resource.'
  97   end
  98
  99   newparam(:match) do
 100     desc 'An optional ruby regular expression to run against existing lines in the file.' \
 101          ' If a match is found, we replace that line rather than adding a new line.' \
 102          ' A regex comparison is performed against the line value and if it does not' \
 103          ' match an exception will be raised.'
 104   end
 105
 106   newparam(:match_for_absence) do
 107     desc 'An optional value to determine if match should be applied when ensure => absent.' \
 108          ' If set to true and match is set, the line that matches match will be deleted.' \
 109          ' If set to false (the default), match is ignored when ensure => absent.' \
 110          ' When `ensure => present`, match_for_absence is ignored.'
 111     newvalues(true, false)
 112     defaultto false
 113   end
 114
 115   newparam(:multiple) do
 116     desc 'An optional value to determine if match can change multiple lines.' \
 117          ' If set to false, an exception will be raised if more than one line matches'
 118     newvalues(true, false)
 119   end
 120
 121   newparam(:after) do
 122     desc 'An optional value used to specify the line after which we will add any new lines. (Existing lines are added in place)' \
 123          ' This is also takes a regex.'
 124   end
 125
 126   # The line property never changes; the type only ever performs a create() or
 127   # destroy(). line is a property in order to allow it to correctly handle
 128   # Sensitive type values. Because it is a property which will never change,
 129   # it should never be considered out of sync.
 130   newproperty(:line) do
 131     desc 'The line to be appended to the file or used to replace matches found by the match attribute.'
 132
 133     def retrieve
 134       @resource[:line]
 135     end
 136   end
 137
 138   newparam(:path) do
 139     desc 'The file Puppet will ensure contains the line specified by the line parameter.'
 140     validate do |value|
 141       unless Puppet::Util.absolute_path?(value)
 142         raise Puppet::Error, "File paths must be fully qualified, not '#{value}'"
 143       end
 144     end
 145   end
 146
 147   newparam(:replace) do
 148     desc 'If true, replace line that matches. If false, do not write line if a match is found'
 149     newvalues(true, false)
 150     defaultto true
 151   end
 152
 153   newparam(:replace_all_matches_not_matching_line) do
 154     desc 'Configures the behavior of replacing all lines in a file which match the `match` parameter regular expression, regardless of whether the specified line is already present in the file.'
 155
 156     newvalues(true, false)
 157     defaultto false
 158   end
 159
 160   newparam(:encoding) do
 161     desc 'For files that are not UTF-8 encoded, specify encoding such as iso-8859-1'
 162     defaultto 'UTF-8'
 163   end
 164
 165   newparam(:append_on_no_match) do
 166     desc 'If true, append line if match is not found. If false, do not append line if a match is not found'
 167     newvalues(true, false)
 168     defaultto true
 169   end
 170
 171   # Autorequire the file resource if it's being managed
 172   autorequire(:file) do
 173     self[:path]
 174   end
 175
 176   validate do
 177     if self[:replace_all_matches_not_matching_line].to_s == 'true' && self[:multiple].to_s == 'false'
 178       raise(Puppet::Error, 'multiple must be true when replace_all_matches_not_matching_line is true')
 179     end
 180     if self[:replace_all_matches_not_matching_line].to_s == 'true' && self[:replace].to_s == 'false'
 181       raise(Puppet::Error, 'replace must be true when replace_all_matches_not_matching_line is true')
 182     end
 183     unless self[:line]
 184       unless (self[:ensure].to_s == 'absent') && (self[:match_for_absence].to_s == 'true') && self[:match]
 185         raise(Puppet::Error, 'line is a required attribute')
 186       end
 187     end
 188     unless self[:path]
 189       raise(Puppet::Error, 'path is a required attribute')
 190     end
 191   end
 192 end