puppet 0.24.6 → 0.24.7

data/lib/puppet/util/rdoc/parser.rb

@@ -0,0 +1,437 @@
+# Puppet "parser" for the rdoc system
+# The parser uses puppet parser and traverse the AST to instruct RDoc about
+# our current structures. It also parses ruby files that could contain
+# either custom facts or puppet plugins (functions, types...)
+
+# rdoc mandatory includes
+require "rdoc/code_objects"
+require "puppet/util/rdoc/code_objects"
+require "rdoc/tokenstream"
+require "rdoc/markup/simple_markup/preprocess"
+require "rdoc/parsers/parserfactory"
+
+module RDoc
+
+class Parser
+    extend ParserFactory
+
+    # parser registration into RDoc
+    parse_files_matching(/\.(rb|pp)$/)
+
+    # called with the top level file
+    def initialize(top_level, file_name, content, options, stats)
+        @options = options
+        @stats   = stats
+        @input_file_name = file_name
+        @top_level = PuppetTopLevel.new(top_level)
+        @progress = $stderr unless options.quiet
+    end
+
+    # main entry point
+    def scan
+        Puppet.info "rdoc: scanning %s" % @input_file_name
+        if @input_file_name =~ /\.pp$/
+            @parser = Puppet::Parser::Parser.new(:environment => Puppet[:environment])
+            @parser.file = @input_file_name
+            @ast = @parser.parse
+        end
+        scan_top_level(@top_level)
+        @top_level
+    end
+
+    private
+
+    # walk down the namespace and lookup/create container as needed
+    def get_class_or_module(container, name)
+
+        # class ::A -> A is in the top level
+        if name =~ /^::/
+            container = @top_level
+        end
+
+        names = name.split('::')
+
+        final_name = names.pop
+        names.each do |name|
+            prev_container = container
+            container = container.find_module_named(name)
+            unless container
+                container = prev_container.add_module(PuppetClass, name)
+            end
+        end
+        return [container, final_name]
+    end
+
+    # split_module tries to find if +path+ belongs to the module path
+    # if it does, it returns the module name, otherwise if we are sure
+    # it is part of the global manifest path, "<site>" is returned.
+    # And finally if this path couldn't be mapped anywhere, nil is returned.
+    def split_module(path)
+        # find a module
+        fullpath = File.expand_path(path)
+        Puppet.debug "rdoc: testing %s" % fullpath
+        if fullpath =~ /(.*)\/([^\/]+)\/(?:manifests|plugins)\/.+\.(pp|rb)$/
+            modpath = $1
+            name = $2
+            Puppet.debug "rdoc: module %s into %s ?" % [name, modpath]
+            Puppet::Module.modulepath().each do |mp|
+                if File.identical?(modpath,mp)
+                    Puppet.debug "rdoc: found module %s" % name
+                    return name
+                end
+            end
+        end
+        if fullpath =~ /\.(pp|rb)$/
+            # there can be paths we don't want to scan under modules
+            # imagine a ruby or manifest that would be distributed as part as a module
+            # but we don't want those to be hosted under <site>
+            Puppet::Module.modulepath().each do |mp|
+                # check that fullpath is a descendant of mp
+                dirname = fullpath
+                while (dirname = File.dirname(dirname)) != '/'
+                    return nil if File.identical?(dirname,mp)
+                end
+            end
+        end
+        # we are under a global manifests
+        Puppet.debug "rdoc: global manifests"
+        return "<site>"
+    end
+
+    # create documentation for the top level +container+
+    def scan_top_level(container)
+        # use the module README as documentation for the module
+        comment = ""
+        readme = File.join(File.dirname(File.dirname(@input_file_name)), "README")
+        comment = File.open(readme,"r") { |f| f.read } if FileTest.readable?(readme)
+        look_for_directives_in(container, comment) unless comment.empty?
+
+        # infer module name from directory
+        name = split_module(@input_file_name)
+        if name.nil?
+            # skip .pp files that are not in manifests directories as we can't guarantee they're part
+            # of a module or the global configuration.
+            container.document_self = false
+            return
+        end
+
+        Puppet.debug "rdoc: scanning for %s" % name
+
+        container.module_name = name
+        container.global=true if name == "<site>"
+
+        @stats.num_modules += 1
+        container, name  = get_class_or_module(container,name)
+        mod = container.add_module(PuppetModule, name)
+        mod.record_location(@top_level)
+        mod.comment = comment
+
+        if @input_file_name =~ /\.pp$/
+            parse_elements(mod)
+        elsif @input_file_name =~ /\.rb$/
+            parse_plugins(mod)
+        end
+    end
+
+    # create documentation for include statements we can find in +code+
+    # and associate it with +container+
+    def scan_for_include(container, code)
+        code.each do |stmt|
+            scan_for_include(container,stmt.children) if stmt.is_a?(Puppet::Parser::AST::ASTArray)
+
+            if stmt.is_a?(Puppet::Parser::AST::Function) and stmt.name == "include"
+                stmt.arguments.each do |included|
+                    Puppet.debug "found include: %s" % included.value
+                    container.add_include(Include.new(included.value, stmt.doc))
+                end
+            end
+        end
+    end
+
+    # create documentation for global variables assignements we can find in +code+
+    # and associate it with +container+
+    def scan_for_vardef(container, code)
+        code.each do |stmt|
+            scan_for_vardef(container,stmt.children) if stmt.is_a?(Puppet::Parser::AST::ASTArray)
+
+            if stmt.is_a?(Puppet::Parser::AST::VarDef)
+                Puppet.debug "rdoc: found constant: %s = %s" % [stmt.name.to_s, value_to_s(stmt.value)]
+                container.add_constant(Constant.new(stmt.name.to_s, value_to_s(stmt.value), stmt.doc))
+            end
+        end
+    end
+
+    # create documentation for resources we can find in +code+
+    # and associate it with +container+
+    def scan_for_resource(container, code)
+        code.each do |stmt|
+            scan_for_resource(container,stmt.children) if stmt.is_a?(Puppet::Parser::AST::ASTArray)
+
+            if stmt.is_a?(Puppet::Parser::AST::Resource) and !stmt.type.nil?
+                type = stmt.type.split("::").collect { |s| s.capitalize }.join("::")
+                title = value_to_s(stmt.title)
+                Puppet.debug "rdoc: found resource: %s[%s]" % [type,title]
+
+                param = []
+                stmt.params.children.each do |p|
+                    res = {}
+                    res["name"] = p.param
+                    if !p.value.nil?
+                        if !p.value.is_a?(Puppet::Parser::AST::ASTArray)
+                            res["value"] = "'#{p.value}'"
+                        else
+                            res["value"] = "[%s]" % p.value.children.collect { |v| "'#{v}'" }.join(", ")
+                        end
+                    end
+                    param << res
+                end
+
+                container.add_resource(PuppetResource.new(type, title, stmt.doc, param))
+            end
+        end
+    end
+
+    # create documentation for a class named +name+
+    def document_class(name, klass, container)
+        Puppet.debug "rdoc: found new class %s" % name
+        container, name = get_class_or_module(container, name)
+
+        superclass = klass.parentclass
+        superclass = "" if superclass.nil? or superclass.empty?
+
+        @stats.num_classes += 1
+        comment = klass.doc
+        look_for_directives_in(container, comment) unless comment.empty?
+        cls = container.add_class(PuppetClass, name, superclass)
+        cls.record_location(@top_level)
+
+        # scan class code for include
+        code = klass.code.children if klass.code.is_a?(Puppet::Parser::AST::ASTArray)
+        code ||= klass.code
+        unless code.nil?
+            scan_for_include(cls, code)
+            scan_for_resource(cls, code) if Puppet.settings[:document_all]
+        end
+
+        cls.comment = comment
+    end
+
+    # create documentation for a node
+    def document_node(name, node, container)
+        Puppet.debug "rdoc: found new node %s" % name
+        superclass = node.parentclass
+        superclass = "" if superclass.nil? or superclass.empty?
+
+        comment = node.doc
+        look_for_directives_in(container, comment) unless comment.empty?
+        n = container.add_node(name, superclass)
+        n.record_location(@top_level)
+
+        code = node.code.children if node.code.is_a?(Puppet::Parser::AST::ASTArray)
+        code ||= node.code
+        unless code.nil?
+            scan_for_include(n, code)
+            scan_for_vardef(n, code)
+            scan_for_resource(n, code) if Puppet.settings[:document_all]
+        end
+
+        n.comment = comment
+    end
+
+    # create documentation for a define
+    def document_define(name, define, container)
+        Puppet.debug "rdoc: found new definition %s" % name
+        # find superclas if any
+        @stats.num_methods += 1
+
+        # find the parentclass
+        # split define name by :: to find the complete module hierarchy
+        container, name = get_class_or_module(container,name)
+
+        return if container.find_local_symbol(name)
+
+        # build up declaration
+        declaration = ""
+        define.arguments.each do |arg,value|
+            declaration << "\$#{arg}"
+            if !value.nil?
+                declaration << " => "
+                if !value.is_a?(Puppet::Parser::AST::ASTArray)
+                    declaration << "'#{value.value}'"
+                else
+                    declaration << "[%s]" % value.children.collect { |v| "'#{v}'" }.join(", ")
+                end
+            end
+            declaration << ", "
+        end
+        declaration.chop!.chop! if declaration.size > 1
+
+        # register method into the container
+        meth =  AnyMethod.new(declaration, name)
+        container.add_method(meth)
+        meth.comment = define.doc
+        look_for_directives_in(container, meth.comment) unless meth.comment.empty?
+        meth.params = "( " + declaration + " )"
+        meth.visibility = :public
+        meth.document_self = true
+        meth.singleton = false
+    end
+
+    # Traverse the AST tree and produce code-objects node
+    # that contains the documentation
+    def parse_elements(container)
+        Puppet.debug "rdoc: scanning manifest"
+        @ast[:classes].each do |name, klass|
+            if klass.file == @input_file_name
+                unless name.empty?
+                    document_class(name,klass,container)
+                else # on main class document vardefs
+                    code = klass.code.children unless klass.code.is_a?(Puppet::Parser::AST::ASTArray)
+                    code ||= klass.code
+                    scan_for_vardef(container, code) unless code.nil?
+                end
+            end
+        end
+
+        @ast[:definitions].each do |name, define|
+            if define.file == @input_file_name
+                document_define(name,define,container)
+            end
+        end
+
+        @ast[:nodes].each do |name, node|
+            if node.file == @input_file_name
+                document_node(name,node,container)
+            end
+        end
+    end
+
+    # create documentation for plugins
+    def parse_plugins(container)
+        Puppet.debug "rdoc: scanning plugin or fact"
+        if @input_file_name =~ /\/facter\/[^\/]+\.rb$/
+            parse_fact(container)
+        else
+            parse_puppet_plugin(container)
+        end
+    end
+
+    # this is a poor man custom fact parser :-)
+    def parse_fact(container)
+        comments = ""
+        current_fact = nil
+        File.open(@input_file_name) do |of|
+            of.each do |line|
+                # fetch comments
+                if line =~ /^[ \t]*# ?(.*)$/
+                    comments += $1 + "\n"
+                elsif line =~ /^[ \t]*Facter.add\(['"](.*?)['"]\)/
+                    current_fact = Fact.new($1,{})
+                    container.add_fact(current_fact)
+                    look_for_directives_in(container, comments) unless comments.empty?
+                    current_fact.comment = comments
+                    current_fact.record_location(@top_level)
+                    comments = ""
+                    Puppet.debug "rdoc: found custom fact %s" % current_fact.name
+                elsif line =~ /^[ \t]*confine[ \t]*:(.*?)[ \t]*=>[ \t]*(.*)$/
+                    current_fact.confine = { :type => $1, :value => $2 } unless current_fact.nil?
+                else # unknown line type
+                    comments =""
+                end
+            end
+        end
+    end
+
+    # this is a poor man puppet plugin parser :-)
+    # it doesn't extract doc nor desc :-(
+    def parse_puppet_plugin(container)
+        comments = ""
+        current_plugin = nil
+
+        File.open(@input_file_name) do |of|
+            of.each do |line|
+                # fetch comments
+                if line =~ /^[ \t]*# ?(.*)$/
+                    comments += $1 + "\n"
+                elsif line =~ /^[ \t]*newfunction[ \t]*\([ \t]*:(.*?)[ \t]*,[ \t]*:type[ \t]*=>[ \t]*(:rvalue|:lvalue)\)/
+                    current_plugin = Plugin.new($1, "function")
+                    container.add_plugin(current_plugin)
+                    look_for_directives_in(container, comments) unless comments.empty?
+                    current_plugin.comment = comments
+                    current_plugin.record_location(@top_level)
+                    comments = ""
+                    Puppet.debug "rdoc: found new function plugins %s" % current_plugin.name
+                elsif line =~ /^[ \t]*Puppet::Type.newtype[ \t]*\([ \t]*:(.*?)\)/
+                    current_plugin = Plugin.new($1, "type")
+                    container.add_plugin(current_plugin)
+                    look_for_directives_in(container, comments) unless comments.empty?
+                    current_plugin.comment = comments
+                    current_plugin.record_location(@top_level)
+                    comments = ""
+                    Puppet.debug "rdoc: found new type plugins %s" % current_plugin.name
+                elsif line =~ /module Puppet::Parser::Functions/
+                    # skip
+                else # unknown line type
+                    comments =""
+                end
+            end
+        end
+    end
+
+    # look_for_directives_in scans the current +comment+ for RDoc directives
+    def look_for_directives_in(context, comment)
+        preprocess = SM::PreProcess.new(@input_file_name, @options.rdoc_include)
+
+        preprocess.handle(comment) do |directive, param|
+            case directive
+            when "stopdoc"
+                context.stop_doc
+                ""
+            when "startdoc"
+                context.start_doc
+                context.force_documentation = true
+                ""
+            when "enddoc"
+                #context.done_documenting = true
+                #""
+                throw :enddoc
+            when "main"
+                options = Options.instance
+                options.main_page = param
+                ""
+            when "title"
+                options = Options.instance
+                options.title = param
+                ""
+            when "section"
+                context.set_current_section(param, comment)
+                comment.replace("") # 1.8 doesn't support #clear
+                break
+            else
+                warn "Unrecognized directive '#{directive}'"
+                break
+            end
+        end
+        remove_private_comments(comment)
+    end
+
+    def remove_private_comments(comment)
+        comment.gsub!(/^#--.*?^#\+\+/m, '')
+        comment.sub!(/^#--.*/m, '')
+    end
+
+    # convert an AST value to a string
+    def value_to_s(value)
+        value = value.children if value.is_a?(Puppet::Parser::AST::ASTArray)
+        if value.is_a?(Array)
+            "['#{value.join(", ")}']"
+        elsif [:true, true, "true"].include?(value)
+            "true"
+        elsif [:false, false, "false"].include?(value)
+            "false"
+        else
+            value.to_s
+        end
+    end
+end
+end

data/lib/puppet/util/selinux.rb

@@ -1,74 +1,67 @@
 # Provides utility functions to help interfaces Puppet to SELinux.
 #
-# Currently this is implemented via the command line tools.  At some
-# point support should be added to use the new SELinux ruby bindings
-# as that will be faster and more reliable then shelling out when they
-# are available.  At this time (2008-09-26) these bindings aren't bundled on
-# any SELinux-using distribution I know of.
+# This requires the very new SELinux Ruby bindings.  These bindings closely
+# mirror the SELinux C library interface.
+#
+# Support for the command line tools is not provided because the performance
+# was abysmal.  At this time (2008-11-02) the only distribution providing
+# these Ruby SELinux bindings which I am aware of is Fedora (in libselinux-ruby).
 
-require 'puppet/util'
+begin
+    require 'selinux'
+rescue LoadError
+    # Nothing
+end
 
 module Puppet::Util::SELinux
 
-    include Puppet::Util
-
     def selinux_support?
-        FileTest.exists?("/selinux/enforce")
+        unless defined? Selinux
+            return false
+        end
+        if Selinux.is_selinux_enabled == 1
+            return true
+        end
+        return false
     end
 
     # Retrieve and return the full context of the file.  If we don't have
-    # SELinux support or if the stat call fails then return nil.
+    # SELinux support or if the SELinux call fails then return nil.
     def get_selinux_current_context(file)
         unless selinux_support?
             return nil
         end
-        context = ""
-        begin
-            execpipe("/usr/bin/stat -c %C #{file}") do |out|
-                out.each do |line|
-                    context << line
-                end
-            end
-        rescue Puppet::ExecutionFailure
-            return nil
-        end
-        context.chomp!
-        # Handle the case that the system seems to have SELinux support but
-        # stat finds unlabled files.
-        if context == "(null)"
+        retval = Selinux.lgetfilecon(file)
+        if retval == -1
             return nil
         end
-        return context
+        return retval[1]
     end
 
-    # Use the matchpathcon command, if present, to return the SELinux context
-    # which the SELinux policy on the system expects the file to have.  We can
-    # use this to obtain a good default context.  If the command does not
-    # exist or the call fails return nil.
-    #
-    # Note: For this command to work a full, non-relative, filesystem path
-    # should be given.
+    # Retrieve and return the default context of the file.  If we don't have
+    # SELinux support or if the SELinux call fails to file a default then return nil.
     def get_selinux_default_context(file)
         unless selinux_support?
             return nil
         end
-        unless FileTest.executable?("/usr/sbin/matchpathcon")
+        # If the filesystem has no support for SELinux labels, return a default of nil
+        # instead of what matchpathcon would return
+        unless selinux_label_support?(file)
             return nil
         end
-        context = ""
+        # If the file exists we should pass the mode to matchpathcon for the most specific
+        # matching.  If not, we can pass a mode of 0.
         begin
-            execpipe("/usr/sbin/matchpathcon #{file}") do |out|
-                out.each do |line|
-                    context << line
-                end
-            end
-        rescue Puppet::ExecutionFailure
+            filestat = File.lstat(file)
+            mode = filestat.mode
+        rescue Errno::ENOENT
+            mode = 0
+        end
+        retval = Selinux.matchpathcon(file, mode)
+        if retval == -1
             return nil
         end
-        # For a successful match, matchpathcon returns two fields separated by
-        # a variable amount of whitespace.  The second field is the full context.
-        context = context.split(/\s/)[1]
-        return context
+        return retval[1]
     end
 
     # Take the full SELinux context returned from the tools and parse it
@@ -91,32 +84,52 @@ module Puppet::Util::SELinux
     end
 
     # This updates the actual SELinux label on the file.  You can update
-    # only a single component or update the entire context.  It is just a
-    # wrapper around the chcon command.
+    # only a single component or update the entire context.
+    # The caveat is that since setting a partial context makes no sense the
+    # file has to already exist.  Puppet (via the File resource) will always
+    # just try to set components, even if all values are specified by the manifest.
+    # I believe that the OS should always provide at least a fall-through context
+    # though on any well-running system.
     def set_selinux_context(file, value, component = false)
         unless selinux_support?
             return nil
         end
-        case component
-            when :seluser
-                flag = "-u"
-            when :selrole
-                flag = "-r"
-            when :seltype
-                flag = "-t"
-            when :selrange
-                flag = "-l"
-            else
-                flag = nil
-        end
 
-        if flag.nil?
-            cmd = ["/usr/bin/chcon","-h",value,file]
+        if component
+            # Must first get existing context to replace a single component
+            context = Selinux.lgetfilecon(file)[1]
+            if context == -1
+                # We can't set partial context components when no context exists
+                # unless/until we can find a way to make Puppet call this method
+                # once for all selinux file label attributes.
+                Puppet.warning "Can't set SELinux context on file unless the file already has some kind of context"
+                return nil
+            end
+            context = context.split(':')
+            case component
+                when :seluser
+                    context[0] = value
+                when :selrole
+                    context[1] = value
+                when :seltype
+                    context[2] = value
+                when :selrange
+                    context[3] = value
+                else
+                    raise ArguementError, "set_selinux_context component must be one of :seluser, :selrole, :seltype, or :selrange"
+            end
+            context = context.join(':')
+        else
+            context = value
+        end
+       
+        retval = Selinux.lsetfilecon(file, context)
+        if retval == 0
+            return true
         else
-            cmd = ["/usr/bin/chcon","-h",flag,value,file]
+            Puppet.warning "Failed to set SELinux context %s on %s" % [context, file]
+            return false
         end
-        execute(cmd)
-        return true
     end
 
     # Since this call relies on get_selinux_default_context it also needs a
@@ -136,4 +149,63 @@ module Puppet::Util::SELinux
         end
         return nil
     end
+
+    # Internal helper function to read and parse /proc/mounts
+    def read_mounts
+        begin
+            mounts = File.read("/proc/mounts")
+        rescue
+            return nil
+        end
+
+        mntpoint = {}
+
+        # Read all entries in /proc/mounts.  The second column is the
+        # mountpoint and the third column is the filesystem type.
+        # We skip rootfs because it is always mounted at /
+        mounts.collect do |line|
+            params = line.split(' ')
+            next if params[2] == 'rootfs'
+            mntpoint[params[1]] = params[2]
+        end
+        return mntpoint
+    end
+
+    # Internal helper function to return which type of filesystem a
+    # given file path resides on
+    def find_fs(file)
+        unless mnts = read_mounts()
+            return nil
+        end
+       
+        # For a given file:
+        # Check if the filename is in the data structure; 
+        #   return the fstype if it is.
+        # Just in case: return something if you're down to "/" or ""
+        # Remove the last slash and everything after it, 
+        #   and repeat with that as the file for the next loop through.
+        ary = file.split('/')
+        while not ary.empty? do
+            path = ary.join('/')
+            if mnts.has_key?(path)
+                return mnts[path]
+            end
+            ary.pop
+        end
+        return mnts['/']
+    end
+
+    # Check filesystem a path resides on for SELinux support against
+    # whitelist of known-good filesystems.
+    # Returns true if the filesystem can support SELinux labels and
+    # false if not.
+    def selinux_label_support?(file)
+        fstype = find_fs(file)
+        if fstype.nil?
+            return false
+        end
+        filesystems = ['ext2', 'ext3', 'ext4', 'gfs', 'gfs2', 'xfs', 'jfs']
+        return filesystems.include?(fstype)
+    end
+
 end