bootscript 0.2.1

checksums.yaml

@@ -0,0 +1,15 @@
+---
+!binary "U0hBMQ==":
+  metadata.gz: !binary |-
+    YTE3ZDJjZGM2OThiYzk4NzE2MjVkZTBhZTNhMTFmODc4ZDJlYTJhNQ==
+  data.tar.gz: !binary |-
+    N2VlMThiNzdhNDYwYTQwN2E3MzAwZjM0OWJkODVhYmRiMDg4MzU5Zg==
+SHA512:
+  metadata.gz: !binary |-
+    ZDFkYmVmN2M4ZGI3ODljMzUxODAwYjg4OWFmNTliOTU3NTcyN2M1YWZmY2Fj
+    OTRhNWUzNzM2OGUzODBmZjFhYWUzMzNhNjU0NWMyNDM2MzU5ZDE5OWU3YWJl
+    YjJkZmQ2ZDhkMzhjNjM2ZmIwOTNiNmViMmRmYTIwMmQ0ZDEwOWU=
+  data.tar.gz: !binary |-
+    NjgwZjE5MjA4ZDg3YWIyZGI4MzI2MTA4MDg4MzQ2NzM3MWViNDY2YmExZmY0
+    ZWM1Njg1ODg0YzAxNTE0M2ZjZDcyNzk4NmYxNjg5YTE3YjJlZGY1MmQxZmUw
+    OThlMDJhYmY1YjJkZmZmNjM4Y2MyM2Q5ODg4NGVlNDRhM2I5YTY=

data/.gitignore

@@ -0,0 +1,17 @@
+*.gem
+*.rbc
+.bundle
+.config
+.yardoc
+Gemfile.lock
+InstalledFiles
+_yardoc
+coverage
+doc/
+lib/bundler/man
+pkg
+rdoc
+spec/reports
+test/tmp
+test/version_tmp
+tmp

data/.rspec

@@ -0,0 +1 @@
+--color --format documentation -r ./spec/spec_helper.rb

data/ERB_VARS.md

@@ -0,0 +1,30 @@
+List of Template Variables
+================
+Here is a list of all the keys that a call to `Bootscript.generate` will check for, and how they affect the gem's behavior.
+
+
+Main settings
+----------------
+* `:platform` - when set to `:unix` (default), the gem produces a Bash script as output. When set to `:windows`, the gem produces Powershell wrapped in a Batch script.
+* `:startup_command` - The command to be executed after the archive is extracted. If Chef support is enabled (by setting `chef_validation_pem`), this value defaults to a platform-specific command that invokes the built-in Chef support. Otherwise, it defaults to `nil`, and no startup command is executed. In either case, it can be overridden.
+* `:update_os` - If `true`, will attempt to upgrade all the operating system packages. Defaults to `false`. _(Debian/Ubuntu only for now.)_
+* `:add_script_tags` - _(Windows only.)_ When set to `true`, encloses the output in `<SCRIPT>...</SCRIPT>` XML tags, usually required for AWS.
+
+
+Chef settings
+----------------
+The Chef-based examples in the README illustrate the included Chef support.
+* `:chef_validation_pem` - When set to any non-nil value, enables the built-in Chef support. The value must be the key data itself, so read it into memory first.
+* `:chef_databag_secret` - The secret used to decrypt the Chef org's encrypted data bag items.
+* `:chef_attributes` - a Hash of Chef attributes that is read as `node[chef_client][config]` by the [Opscode chef-client cookbook][1]. This is where you specify your `node_name` (if desired), `chef_server_url`, `validation_client_name`, etc. *Always use strings for chef attribute keys, not symbols!*
+
+
+RAMdisk settings
+----------------
+* `:create_ramdisk` - Setting this to `true` generates a bootscript that creates a RAMdisk of a configurable size and at a configurable filesystem location. This happens even before the archive is unpacked, so you can extract files into the RAMdisk.
+* `:ramdisk_mount` - The filesystem location where the RAMdisk is mounted. (defaults to `false`)
+* `:ramdisk_size` - Size, in Megabytes, of the RAMdisk. (defaults to 20)
+
+
+--------
+[1]:https://github.com/opscode-cookbooks/chef-client

data/Gemfile

@@ -0,0 +1,2 @@
+source 'https://rubygems.org'
+gemspec

data/LICENSE.txt

@@ -0,0 +1,22 @@
+Copyright (c) 2014 Benton Roberts
+
+MIT License
+
+Permission is hereby granted, free of charge, to any person obtaining
+a copy of this software and associated documentation files (the
+"Software"), to deal in the Software without restriction, including
+without limitation the rights to use, copy, modify, merge, publish,
+distribute, sublicense, and/or sell copies of the Software, and to
+permit persons to whom the Software is furnished to do so, subject to
+the following conditions:
+
+The above copyright notice and this permission notice shall be
+included in all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
+EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
+MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND
+NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE
+LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION
+OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION
+WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

data/README.md

@@ -0,0 +1,176 @@
+Bootscript
+================
+Constructs a self-extracting archive, wrapped in a Bash script (or Windows batch script), for securely initializing cloud systems.
+
+  *BETA VERSION - needs more functional testing and broader OS support*
+
+----------------
+What is it?
+----------------
+The bootscript gem enables simple creation of a self-extracting "TAR archive within a Bash script", which can be composed from any set of binary or text files -- including support for ERB templates. Any Hash of Ruby values can be interpolated into these templates when they are rendered, and the resulting "boot script" (complete with the base64-encoded archive at the end) can be invoked on nearly any Unix or Windows system to:
+
+* create a RAMdisk for holding the archive contents, which are presumably secrets (this step is optional, and does not yet work on Windows)
+* extract the archived files
+* delete itself
+* execute a user-specified command for further configuration
+
+An extra, optional submodule is also supplied that leverages the above process to install Chef (omnibus), assign arbitrary node attributes (using the same Hash mentioned above), and kick off convergence for a given run list.
+
+
+----------------
+Why is it?
+----------------
+* makes specification of complex, cross-platform boot data simple and portable.
+* simplifies initial Chef setup
+
+----------------
+Where is it? (Installation)
+----------------
+Install the gem and its dependencies from RubyGems:
+
+    gem install bootscript
+
+
+----------------
+How is it [done]? (Usage)
+----------------
+Call the gem's main public method: `Bootscript.generate()`. It accepts a Hash of template variables as its first argument, which is passed directly to any ERB  template files as they render. All the data in the Hash is available to the templates, but some of the key-value pairs also control the gem's rendering behavior, as demonstrated in the following examples. (There's also a [list of such variables](ERB_VARS.md).)
+
+
+### Simplest - make a RAMdisk
+
+    require 'bootscript'
+    script = Bootscript.generate(
+      create_ramdisk:    true,                # default mount is /etc/secrets
+      startup_command:  'df -h /etc/secrets'  # show the RAMdisk's free space
+    )
+    puts "Now run this as root on any unix node that has `bash` installed:"
+    puts script
+
+
+### Simple - render and install a bash script, then run it
+
+To include some files inside the script's archive, create a "data map", which is a Hash that maps locations on the boot target's filesystem to the values that will be written there when the script is run. The following example generates a script that, when executed, writes some text into the file `/root/hello.sh`.
+
+    # Define a simple shell script, to be written to the node's filesystem:
+    data_map = {'/root/hello.sh' => 'echo Hello, <%= my_name %>.'}
+    puts Bootscript.generate({
+        my_name:          ENV['USER'],          # evaluated now, at generation
+        startup_command:  'sh /root/hello.sh',  # run on the node, after unarchiving
+      }, data_map
+    )
+
+_(Can you guess what it will print on the node that runs the script?)_
+
+
+### Chef support, using the included templates (single node)
+
+The software's Chef support includes some predefined template files that will install the Chef client sofware, and then kick off the convergence process. These templates are automatically included into the boot script when you pass a `:chef_validation_pem` to the `generate()` method, so no data map is required for this example.
+
+The two Chef secrets are passed directly to `generate`, so they should be read from the filesystem if necessary...
+
+    VALIDATION_CERT = File.read "#{ENV['HOME']}/.chef/myorg-validator.pem"
+    DATABAG_SECRET = File.read "#{ENV['HOME']}/.chef/myorg-databag-secret.txt"
+
+    require 'uuid'                                    # Make some unique boot data
+    NODE_UUID = UUID.generate                         # for just this one node...
+    puts Bootscript.generate(
+      logger:               Logger.new(STDOUT),       # Monitor progress
+      create_ramdisk:       true,                     # make a RAMdisk
+      chef_validation_pem:  VALIDATION_CERT,          # the data, not the path!
+      chef_databag_secret:  DATABAG_SECRET,           # same here - the secret data
+      chef_attributes: {    # ALWAYS USE STRINGS FOR CHEF ATTRIBUTE KEYS!
+        'run_list' => 'role[my_app_server]',
+        'chef_client' => {
+          'config' => {
+            'node_name' => "myproject-myenv-#{NODE_UUID}",
+            'chef_server_url' => "https://api.opscode.com/organizations/myorg",
+            'validation_client_name' => "myorg-validator",
+          }
+        }
+      }
+    )
+
+
+The validation certificate and data bag secrets will be saved in a `chef` directory below the RAMdisk mount point, then symlinked into `/etc/chef`. You should use this technique for all the files you put into the `data_map` that contain secrets!
+
+### Chef support, with the node name determined by the node
+
+This is just like the previous example, only first you create a ruby file that will run on the node at boot time, to compute the node name. This can also be a template, like `/tmp/set_node_name.rb.erb`:
+
+    unless node_name
+      # filled in at publish() time by the bootstrap gem
+      name = '<%= project %>.<%= stage %>.<%= tier %>'
+      require 'ohai'
+      ohai = Ohai::System.new
+      ohai.all_plugins
+      if ohai[:ec2] && ohai[:ec2][:instance_id]
+        name = "#{name}.#{ohai[:ec2][:instance_id]}"
+      else
+        name = "#{name}.#{rand(2**(0.size * 8 -2) -1)}"
+      end
+      puts "Setting node name to #{name}..."
+      node_name name
+    end
+
+Now tell the boot script to put the ruby file where chef-client will pick it up (thanks, Opscode!). Note that when including an ERB file into the boot archive, the value in the data map should be an existing Ruby File object, not a String:
+
+    data_map = {
+      '/etc/chef/client.d/set_node_name.rb' => File.new("/tmp/set_node_name.rb.erb")
+    }
+
+Finally, generate *without* an explicit node name, but filling in the other values that are known at the time. Don't forget to pass the data map as the second argument to `generate()`.
+
+    PROJECT, STAGE, TIER = 'myapp', 'testing', 'db'
+    script = Bootscript.generate({
+      project:              PROJECT,  # As before, these values are rendered
+      stage:                STAGE,    # into the above ruby template.
+      tier:                 TIER,
+      chef_attributes: {
+        'run_list' => 'role[my_app_server]',
+        'chef_client' => {            # NOTE - no node_name passed here,
+          'config' => {               # but the rest is the same...
+            'chef_server_url' => "https://api.opscode.com/organizations/myorg",
+            'validation_client_name' => "myorg-validator",
+          }
+        }
+      },
+      chef_validation_pem:  VALIDATION_CERT,
+      chef_databag_secret:  DATABAG_SECRET,
+    }, data_map)
+
+
+----------------
+*Known Limitations / Bugs*
+----------------
+* bash and tar are required on Unix boot targets
+* Powershell is required on Windows boot targets
+* bash, tar and uudecode are required to run the tests
+
+
+----------------
+Who is it? (Contribution)
+----------------
+This Gem was created by Benton Roberts _(benton@bentonroberts.com)_
+
+The project is still in its early stages. Helping hands are appreciated.
+
+1) Install project dependencies.
+
+    gem install rake bundler
+
+2) Fetch the project code and bundle up...
+
+    git clone https://github.com/benton/bootscript.git
+    cd bootscript
+    bundle
+
+3) Run the tests:
+
+    bundle exec rake
+
+4) Autotest while you work:
+
+    bundle exec autotest
+
+

data/Rakefile

@@ -0,0 +1,8 @@
+require 'bundler/gem_tasks'
+require 'rspec/core/rake_task'
+
+desc 'Default: Run specs'
+task :default => :spec
+
+desc "Run specs"
+RSpec::Core::RakeTask.new # options read from .rspec

data/bootscript.gemspec

@@ -0,0 +1,31 @@
+# coding: utf-8
+lib = File.expand_path('../lib', __FILE__)
+$LOAD_PATH.unshift(lib) unless $LOAD_PATH.include?(lib)
+require 'bootscript/version'
+
+Gem::Specification.new do |spec|
+  spec.name          = "bootscript"
+  spec.version       = Bootscript::VERSION
+  spec.authors       = ["Benton Roberts"]
+  spec.email         = ["benton@bentonroberts.com"]
+  spec.description   = %q{Constructs a self-extracting archive, wrapped in a script, for securely initializing cloud systems}
+  spec.summary       = %q{Constructs a self-extracting archive, wrapped in a script, for securely initializing cloud systems}
+  spec.homepage      = "http://github.com/benton/bootscript"
+  spec.license       = "MIT"
+
+  spec.files         = `git ls-files`.split($/)
+  spec.executables   = spec.files.grep(%r{^bin/}) { |f| File.basename(f) }
+  spec.test_files    = spec.files.grep(%r{^(test|spec|features)/})
+  spec.require_paths = ["lib"]
+
+  spec.add_dependency "erubis"
+  spec.add_dependency "minitar"
+  spec.add_dependency "rubyzip"
+  spec.add_dependency "json"
+
+  spec.add_development_dependency "bundler", "~> 1.3"
+  spec.add_development_dependency "rake"
+  spec.add_development_dependency "rspec"
+  spec.add_development_dependency "ZenTest"
+  spec.add_development_dependency "yard"
+end

data/lib/bootscript.rb

@@ -0,0 +1,80 @@
+require 'logger'
+require 'bootscript/version'
+require 'bootscript/script'
+require 'bootscript/uu_writer'
+require 'bootscript/chef'
+
+# provides the software's only public method, generate()
+module Bootscript
+
+  # These values are interpolated into all templates, and can be overridden
+  # in calls to {Bootscript#generate}
+  DEFAULT_VARS = {
+    platform:       :unix,          # or :windows
+    create_ramdisk: false,
+    startup_command: '',  # customized by platform if chef used
+    ramdisk_mount:  '',   # customized by platform, see platform_defaults
+    ramdisk_size:   20,   # Megabytes
+    add_script_tags: false,
+    script_name:    'bootscript', # base name of the boot script
+    strip_comments: true,
+    imdisk_url:     'http://www.ltr-data.se/files/imdiskinst.exe',
+    update_os:      false
+  }
+
+  # Generates the full text of a boot script based on the supplied
+  # template_vars and data_map. If no optional destination is supplied,
+  # the full text is returned as a String. Otherwise, the text is
+  # written to the destination using write(), and the number of bytes
+  # written is returned.
+  def self.generate(template_vars = {}, data_map = {}, destination = nil)
+    script = Bootscript::Script.new(template_vars[:logger])
+    script.data_map = data_map
+    script.generate(template_vars, destination)
+  end
+
+  # Returns true if the passed Hash of erb_vars indicate a
+  # Windows boot target
+  def self.windows?(erb_vars)
+    (erb_vars[:platform] || '').to_s.downcase == 'windows'
+  end
+
+  # Returns a slightly-modified version of the default Ruby Logger
+  # @param output [STDOUT, File, etc.] where to write the logs
+  # @param level [DEBUG|INFO|etc.] desired minimum severity
+  # @return [Logger] a standard Ruby Logger with a nicer output format
+  def self.default_logger(output = nil, level = Logger::FATAL)
+    logger = ::Logger.new(output || STDOUT)
+    logger.sev_threshold = level
+    logger.formatter = proc {|lvl, time, prog, msg|
+      "#{lvl} #{time.strftime '%Y-%m-%d %H:%M:%S %Z'}: #{msg}\n"
+    }
+    logger
+  end
+
+  # Returns the passed Hash of template vars, merged over a set of
+  # computed, platform-specific default variables
+  def self.merge_platform_defaults(vars)
+    defaults = DEFAULT_VARS.merge(vars)
+    if defaults[:platform].to_s == 'windows'
+      defaults[:ramdisk_mount]      = 'R:'
+      defaults[:script_name]        = 'bootscript.ps1'
+      if Chef::included?(defaults)
+        defaults[:startup_command]  = 'PowerShell -Command "& '+
+          '{C:/chef/chef-install.ps1}" > c:/chef/bootscript_setup.log 2>&1'
+      end
+    else
+      defaults[:ramdisk_mount]      = '/etc/secrets'
+      defaults[:script_name]        = 'bootscript.sh'
+      if Chef::included?(defaults)
+        defaults[:startup_command]  = 'chef-install.sh'
+      end
+    end
+    defaults.merge(vars)  # return user vars merged over platform defaults
+  end
+
+  BUILTIN_TEMPLATE_DIR  = File.dirname(__FILE__)+"/templates"
+  UNIX_TEMPLATE         = "#{BUILTIN_TEMPLATE_DIR}/bootscript.sh.erb"
+  WINDOWS_TEMPLATE      = "#{BUILTIN_TEMPLATE_DIR}/bootscript.ps1.erb"
+
+end

data/lib/bootscript/chef.rb

@@ -0,0 +1,70 @@
+module Bootscript
+  # provides built-in Chef templates and attributes
+  module Chef
+
+    # returns a map of the built-in Chef templates, in the context of erb_vars
+    # The presence of :chef_validation_pem triggers the inclusion of Chef
+    def self.files(erb_vars)
+      if Bootscript.windows?(erb_vars)
+        files_for_windows(erb_vars)
+      else
+        files_for_unix(erb_vars)
+      end
+    end
+
+    # defines whether or not Chef support will be included in the boot script,
+    # based on the presence of a certain key or keys in erb_vars
+    # @param [Hash] erb_vars template vars to use for determining Chef inclusion
+    # @return [Boolean] true if erb_vars has the key :chef_validation_pem
+    def self.included?(erb_vars = {})
+      erb_vars.has_key? :chef_validation_pem
+    end
+
+    private
+
+    def self.files_for_unix(erb_vars)
+      template_dir = "#{Bootscript::BUILTIN_TEMPLATE_DIR}/chef"
+      { # built-in files
+        '/usr/local/sbin/chef-install.sh' =>
+          File.new("#{template_dir}/chef-install.sh.erb"),
+        '/etc/chef/attributes.json'       =>
+          File.new("#{template_dir}/attributes.json.erb"),
+        '/etc/chef/client.d/include_json_attributes.rb' =>
+          File.new("#{template_dir}/json_attributes.rb.erb"),
+        '/etc/chef/client.rb'             =>
+          File.new("#{template_dir}/chef_client.conf.erb"),
+        # files generated from required ERB vars
+        "#{erb_vars[:ramdisk_mount]}/chef/validation.pem" =>
+          erb_vars[:chef_validation_pem] || '',
+        "#{erb_vars[:ramdisk_mount]}/chef/encrypted_data_bag_secret" =>
+          erb_vars[:chef_databag_secret] || '',
+      }
+    end
+
+    def self.files_for_windows(erb_vars)
+      template_dir = "#{Bootscript::BUILTIN_TEMPLATE_DIR}/chef"
+      files = { # built-in files
+        'chef/chef-install.ps1' =>
+          File.new("#{template_dir}/chef-install.ps1.erb"),
+        'chef/client.rb'        =>
+          File.new("#{template_dir}/chef_client.conf.erb"),
+        'chef/attributes.json'  =>
+          File.new("#{template_dir}/attributes.json.erb"),
+        'chef/client.d/include_json_attributes.rb' =>
+          File.new("#{template_dir}/json_attributes.rb.erb"),
+        # files generated from required ERB vars
+        "chef/validation.pem" =>
+          erb_vars[:chef_validation_pem] || '',
+        "chef/encrypted_data_bag_secret" =>
+          erb_vars[:chef_databag_secret] || '',
+      }
+      if erb_vars[:create_ramdisk]
+        files.merge!(
+          'chef/client.d/ramdisk_secrets.rb' =>
+            File.new("#{template_dir}/ramdisk_secrets.rb.erb"))
+      end
+      files
+    end
+
+  end
+end