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

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