elecksee 1.0.22 → 1.1.0

data/lib/elecksee/lxc.rb

@@ -1,8 +1,9 @@
-require 'elecksee/helpers/base'
+require 'elecksee'
 require 'securerandom'
 require 'shellwords'
 require 'pathname'
 require 'tmpdir'
+require 'rye'
 
 class Lxc
 
@@ -10,6 +11,10 @@ class Lxc
   # begin with '/', and that's dumb. So we'll make our own Pathname,
   # with a #join that uses File
   class Pathname < ::Pathname
+    # Join arguments using ::File.join
+    #
+    # @param args [String] argument list
+    # @return [String]
     def join(*args)
       self.class.new(::File.join(self.to_path, *args))
     end
@@ -17,16 +22,39 @@ class Lxc
 
   include Helpers
 
-  attr_reader :name, :base_path, :lease_file, :preferred_device
+  # @return [String] name of container
+  attr_reader :name
+  # @return [String] base path of container
+  attr_reader :base_path
+  # @return [String] path to dnsmasq lease file
+  attr_reader :lease_file
+  # @return [String] network device to use for ssh connection
+  attr_reader :preferred_device
+  # @return [String, NilClass] path to default ssh key
+  attr_accessor :ssh_key
+  # @return [String, NilClass] ssh password
+  attr_accessor :ssh_password
+  # @return [String, NilClass]  ssh user
+  attr_accessor :ssh_user
 
   class << self
 
     include Helpers
 
+    # @return [Truthy, String] use sudo when required (set to string for custom sudo command)
     attr_accessor :use_sudo
+    # @return [String] base path for containers
     attr_accessor :base_path
+    # @return [Symbol] :mixlib_shellout or :childprocess
     attr_accessor :shellout_helper
-
+    # @return [String, NilClass] path to default ssh key
+    attr_accessor :default_ssh_key
+    # @return [String, NilClass] default ssh password
+    attr_accessor :default_ssh_password
+    # @return [String, NilClass] default ssh user
+    attr_accessor :default_ssh_user
+
+    # @return [String] sudo command
     def sudo
       case use_sudo
       when TrueClass
@@ -36,44 +64,56 @@ class Lxc
       end
     end
 
+    # @return [String] base path for containers
     def base_path
       @base_path || '/var/lib/lxc'
     end
 
-    # List running containers
+    # Currently running container names
+    #
+    # @return [Array<String>]
     def running
       full_list[:running]
     end
 
-    # List stopped containers
+    # Currently stopped container names
+    #
+    # @return [Array<String>]
     def stopped
       full_list[:stopped]
     end
 
-    # List frozen containers
+    # Currently frozen container names
+    #
+    # @return [Array<String>]
     def frozen
       full_list[:frozen]
     end
 
-    # name:: name of container
-    # Returns if container exists
+    # Container currently exists
+    #
+    # @param name [String] name of container
+    # @return [TrueClass, FalseClass]
     def exists?(name)
       list.include?(name)
     end
 
-    # List of containers
+    # List of all containers
+    #
+    # @return [Array<String>] container names
     def list
-      Dir.glob(File.join(base_path, '*')).map do |item|
-        if(File.directory?(item) && File.exists?(File.join(item, 'config')))
-          File.basename(item)
-        end
-      end.compact
+      run_command('lxc-ls', :sudo => true).
+        stdout.split(/\s/).map(&:strip).compact
     end
 
-    # name:: Name of container
-    # Returns information about given container
+    # Information available for given container
+    #
+    # @param name [String] name of container
+    # @return [Hash]
     def info(name)
-      info = run_command("#{sudo}lxc-info -n #{name}", :allow_failure_retry => 3, :allow_failure => true)
+      if(exists?(name))
+        info = run_command("#{sudo}lxc-info -n #{name}", :allow_failure_retry => 3, :allow_failure => true)
+      end
       if(info)
         Hash[
           info.stdout.split("\n").map do |string|
@@ -93,7 +133,9 @@ class Lxc
       end
     end
 
-    # Return full container information list
+    # Full list of containers grouped by state
+    #
+    # @return [Hash]
     def full_list
       res = {}
       list.each do |item|
@@ -104,51 +146,69 @@ class Lxc
       res
     end
 
-    # ip:: IP address
-    # Returns if IP address is alive
+    # IP address is currently active
+    #
+    # @param ip [String]
+    # @return [TrueClass, FalseClass]
     def connection_alive?(ip)
       %x{ping -c 1 -W 1 #{ip}}
       $?.exitstatus == 0
     end
   end
 
-  # name:: name of container
-  # args:: Argument hash
-  #   - :base_path -> path to container directory
-  #   - :dnsmasq_lease_file -> path to lease file
-  #   - :net_device -> network device to use within container for ssh connection
+  # Create new instance
+  #
+  # @param name [String] container name
+  # @param args [Hash]
+  # @option args [String] :base_path path to container
+  # @option args [String] :dnsmasq_lease_file path to lease file
+  # @option args [String] :net_device network device within container for ssh connection
+  # @option args [String] :ssh_key path to ssh key
+  # @option args [String] :ssh_password ssh password
+  # @option args [String] :ssh_user ssh user
   def initialize(name, args={})
     @name = name
     @base_path = args[:base_path] || self.class.base_path
     @lease_file = args[:dnsmasq_lease_file] || '/var/lib/misc/dnsmasq.leases'
     @preferred_device = args[:net_device]
+    @ssh_key = args.fetch(:ssh_key, self.class.default_ssh_key)
+    @ssh_password = args.fetch(:ssh_password, self.class.default_ssh_password)
+    @ssh_user = args.fetch(:ssh_user, self.class.default_ssh_user)
   end
 
-  # Returns if container exists
+  # @return [TrueClass, FalseClass] container exists
   def exists?
     self.class.exists?(name)
   end
 
-  # Returns if container is running
+  # @return [TrueClass, FalseClass] container is currently running
   def running?
     self.class.info(name)[:state] == :running
   end
 
-  # Returns if container is stopped
+  # @return [TrueClass, FalseClass] container is currently stopped
   def stopped?
     self.class.info(name)[:state] == :stopped
   end
 
-  # Returns if container is frozen
+  # @return [TrueClass, FalseClass] container is currently frozen
   def frozen?
     self.class.info(name)[:state] == :frozen
   end
 
-  # retries:: Number of discovery attempt (3 second sleep intervals)
-  # Returns container IP
+  # Current IP address of container
+  #
+  # @param retries [Integer] number of times to retry discovery
+  # @param raise_on_fail [TrueClass, FalseClass] raise exception on failure
+  # @return [String, NilClass] IP address
+  # @note retries are executed on 3 second sleep intervals
   def container_ip(retries=0, raise_on_fail=false)
     (retries.to_i + 1).times do
-      ip = proc_detected_address || hw_detected_address || leased_address || lxc_stored_address
+      ip = info_detected_address ||
+        proc_detected_address ||
+        hw_detected_address ||
+        leased_address ||
+        lxc_stored_address
       if(ip.is_a?(Array))
         # Filter any found loopbacks
         ip.delete_if{|info| info[:device].start_with?('lo') }
@@ -168,7 +228,9 @@ class Lxc
     raise "Failed to detect live IP address for container: #{name}" if raise_on_fail
   end
 
-  # Container address via lxc config file
+  # Container address defined within the container's config file
+  #
+  # @return [String, NilClass] IP address
   def lxc_stored_address
     if(File.exists?(container_config))
       ip = File.readlines(container_config).detect{|line|
@@ -183,7 +245,9 @@ class Lxc
     end
   end
 
-  # Container address via dnsmasq lease
+  # Container address discovered via dnsmasq lease
+  #
+  # @return [String, NilClass] IP address
   def leased_address
     ip = nil
     if(File.exists?(@lease_file))
@@ -202,6 +266,16 @@ class Lxc
     end
   end
 
+  # Container address discovered via info
+  #
+  # @return [String, NilClass] IP address
+  def info_detected_address
+    self.class.info(name)[:ip]
+  end
+
+  # Container address discovered via device
+  #
+  # @return [String, NilClass] IP address
   def hw_detected_address
     if(container_config.readable?)
       hw = File.readlines(container_config).detect{|line|
@@ -222,6 +296,10 @@ class Lxc
     end
   end
 
+  # Container address discovered via process
+  #
+  # @param base [String] path to netns
+  # @return [String, NilClass] IP address
   def proc_detected_address(base='/run/netns')
     if(pid != -1)
       Dir.mktmpdir do |t_dir|
@@ -240,18 +318,19 @@ class Lxc
     end
   end
 
-  # Full path to container
+  # @return [Pathname] path to container
   def container_path
     Pathname.new(@base_path).join(name)
   end
   alias_method :path, :container_path
 
-  # Full path to container configuration file
+  # @return [Pathname] path to configuration file
   def container_config
     container_path.join('config')
   end
   alias_method :config, :container_config
 
+  # @return [Pathname] path to rootfs
   def container_rootfs
     if(File.exists?(config))
       r_path = File.readlines(config).detect do |line|
@@ -262,19 +341,28 @@ class Lxc
   end
   alias_method :rootfs, :container_rootfs
 
+  # Expand path within containers rootfs
+  #
+  # @param path [String] relative path
+  # @return [Pathname] full path within container
   def expand_path(path)
     container_rootfs.join(path)
   end
 
+  # @return [Symbol] current state
   def state
     self.class.info(name)[:state]
   end
 
+  # @return [Integer, Symbol] process ID or :unknown
   def pid
     self.class.info(name)[:pid]
   end
 
   # Start the container
+  #
+  # @param args [Symbol] argument list (:no_daemon to foreground)
+  # @return [self]
   def start(*args)
     if(args.include?(:no_daemon))
       run_command("lxc-start -n #{name}", :sudo => true)
@@ -282,52 +370,73 @@ class Lxc
       run_command("lxc-start -n #{name} -d", :sudo => true)
       wait_for_state(:running)
     end
+    self
   end
 
   # Stop the container
+  #
+  # @return [self]
   def stop
     run_command("lxc-stop -n #{name}", :allow_failure_retry => 3, :sudo => true)
     wait_for_state(:stopped)
+    self
   end
 
   # Freeze the container
+  #
+  # @return [self]
   def freeze
     run_command("lxc-freeze -n #{name}", :sudo => true)
     wait_for_state(:frozen)
+    self
   end
 
   # Unfreeze the container
+  #
+  # @return [self]
   def unfreeze
     run_command("lxc-unfreeze -n #{name}", :sudo => true)
     wait_for_state(:running)
+    self
   end
 
   # Shutdown the container
+  #
+  # @return [self]
   def shutdown
-    run_command("lxc-shutdown -n #{name}", :sudo => true)
-    wait_for_state(:stopped, :timeout => 120)
     # This block is for fedora/centos/anyone else that does not like lxc-shutdown
     if(running?)
       container_command('shutdown -h now')
       wait_for_state(:stopped, :timeout => 120)
       # If still running here, something is wrong
       if(running?)
-        raise "Failed to shutdown container: #{name}"
+        run_command("lxc-stop -n #{name}", :sudo => true)
+        wait_for_state(:stopped, :timeout => 120)
+        if(running?)
+          raise "Failed to shutdown container: #{name}"
+        end
       end
     end
+    self
   end
 
   # Destroy the container
+  #
+  # @return [self]
   def destroy
     unless stopped?
       stop
     end
     run_command("lxc-destroy -n #{name}", :sudo => true)
+    self
   end
 
-  # command:: command string
-  # opts:: option hash (:networking)
-  # Execute command string within container
+  # Execute command within the container
+  #
+  # @param command [String] command to execute
+  # @param opts [Hash] options passed to #tmp_execute_script
+  # @return [CommandResult]
+  # @note container must be stopped
   def execute(command, opts={})
     if(stopped?)
       cmd = Shellwords.split(command)
@@ -347,22 +456,47 @@ class Lxc
     end
   end
 
+  # Execute command within running container
+  #
+  # @param command [String]
+  # @param args [Hash]
+  # @option args [Integer] :timeout
+  # @option args [TrueClass, FalseClass] :live_stream
+  # @option args [TrueClass, FalseClass] :raise_on_failure
+  # @return [CommandResult]
   def direct_container_command(command, args={})
     begin
-      run_command(
-        "ssh root@#{args[:ip] || container_ip} -i /opt/hw-lxc-config/id_rsa -oStrictHostKeyChecking=no '#{command}'",
-        :sudo => true,
-        :timeout => args[:timeout],
-        :live_stream => args[:live_stream]
+      box = Rye::Box.new(
+        args.fetch(:ip, container_ip(3)),
+        :user => ssh_user,
+        :password => ssh_password,
+        :password_prompt => false,
+        :keys => [ssh_key],
+        :safe => false,
+        :paranoid => false
       )
-      true
-    rescue
-      raise if args[:raise_on_failure]
-      false
+      result = box.execute command
+      CommandResult.new(result)
+    rescue Rye::Err => e
+      if(args[:raise_on_failure])
+        raise CommandFailed.new(
+          "Command failed: #{command}",
+          CommandResult.new(e)
+        )
+      else
+        false
+      end
     end
   end
   alias_method :knife_container, :direct_container_command
 
+  # Wait for container to reach given state
+  #
+  # @param desired_state [Symbol]
+  # @param args [Hash]
+  # @option args [Integer] :timeout
+  # @option args [Numeric] :sleep_interval
+  # @return [self]
   def wait_for_state(desired_state, args={})
     args[:sleep_interval] ||= 1.0
     wait_total = 0.0
@@ -370,10 +504,18 @@ class Lxc
       sleep(args[:sleep_interval])
       wait_total += args[:sleep_interval]
     end
+    self
   end
 
-  # command:: command string
-  # Write command to temporary script with networking support wrap
+  # Write command to temporary file with networking enablement wrapper
+  # and yield relative path
+  #
+  # @param command [String]
+  # @param opts [Hash]
+  # @options opts [TrueClass, FalseClass] enable networking
+  # @yield block to execute
+  # @yieldparam command_script [String] path to file
+  # @return [Object] result of block
   def tmp_execute_script(command, opts)
     script_path = "tmp/#{SecureRandom.uuid}"
     File.open(rootfs.join(script_path), 'w') do |file|
@@ -400,23 +542,12 @@ EOS
     end
   end
 
-  # Detect HOME environment variable. If not an acceptable
-  # value, set to /root or /tmp
-  def detect_home(set_if_missing=false)
-    if(ENV['HOME'] && Pathname.new(ENV['HOME']).absolute?)
-      ENV['HOME']
-    else
-      home = File.directory?('/root') && File.writable?('/root') ? '/root' : '/tmp'
-      if(set_if_missing)
-        ENV['HOME'] = home
-      end
-      home
-    end
-  end
-
-  # cmd:: Shell command string
-  # retries:: Number of retry attempts (1 second sleep interval)
-  # Runs command in container via ssh
+  # Run command within container
+  #
+  # @param cmd [String] command to run
+  # @param retries [Integer] number of retry attempts
+  # @return [CommandResult]
+  # @note retries are over 1 second intervals
   def container_command(cmd, retries=1)
     begin
       detect_home(true)
@@ -438,18 +569,9 @@ EOS
     end
   end
 
-  def log
-    if(defined?(Chef))
-      Chef::Log
-    else
-      unless(@logger)
-        require 'logger'
-        @logger = Logger.new('/dev/null')
-      end
-      @logger
-    end
-  end
-
 end
 
+# Make default settings
 Lxc.shellout_helper = :mixlib_shellout
+Lxc.default_ssh_key = '/opt/hw-lxc-config/id_rsa'
+Lxc.default_ssh_user = 'root'

data/lib/elecksee/lxc_file_config.rb

@@ -1,11 +1,21 @@
+require 'elecksee'
+
 class Lxc
+  # Configuration file interface
   class FileConfig
 
+    # @return [Array]
     attr_reader :network
+    # @return [String] path to configuration file
     attr_reader :base
 
     class << self
 
+      # Convert object to Hash if possible
+      #
+      # @param thing [Object]
+      # @return [Hash]
+      # @note used mostly for the lxc resource within chef
       def convert_to_hash(thing)
         if(defined?(Chef) && thing.is_a?(Chef::Resource))
           result = Hash[*(
@@ -26,6 +36,10 @@ class Lxc
         result || thing
       end
 
+      # Symbolize keys within hash
+      #
+      # @param thing [Hashish]
+      # @return [Hash]
       def symbolize_hash(thing)
         if(defined?(Mash))
           Mash.new(thing)
@@ -38,6 +52,10 @@ class Lxc
         end
       end
 
+      # Generate configuration file contents
+      #
+      # @param resource [Hashish]
+      # @return [String]
       def generate_config(resource)
         resource = symbolize_hash(convert_to_hash(resource))
         config = []
@@ -79,6 +97,9 @@ class Lxc
 
     end
 
+    # Create new instance
+    #
+    # @param path [String]
     def initialize(path)
       raise 'LXC config file not found' unless File.exists?(path)
       @path = path
@@ -89,6 +110,9 @@ class Lxc
 
     private
 
+    # Parse the configuration file
+    #
+    # @return [TrueClass]
     def parse!
       cur_net = nil
       File.readlines(@path).each do |line|
@@ -115,6 +139,8 @@ class Lxc
         end
       end
       @network << cur_net if cur_net
+      true
     end
+
   end
 end