dockershell 0.0.1

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA1:
+  metadata.gz: dc4ea96dd7610b476d4fc51ac64945bd935a0c66
+  data.tar.gz: efd2a909162434eaa8446c0bbf7f2f2f578254dd
+SHA512:
+  metadata.gz: 646561ae7ef2869024cbe57e1a2beb868f8e902e5863352fc59c7c29e9cd81d88dc465e32c08a70c66344bf5d8afdc8569fd23ff475773c9a405ad34808f4a29
+  data.tar.gz: 076319a5aaa3af6fe0d01b120904198dfe2c29f04edfd5040d365265d4205f0371a9bced9b5f95030e33c55978493b9358c7c514a408eabe8024337ad8225c99

data/README.md

@@ -0,0 +1,164 @@
+# dockershell
+A simple user shell backed by Docker containers.
+
+#### Table of Contents
+
+1. [Overview](#overview)
+1. [Configuration](#configuration)
+    * [Profiles](#profiles)
+1. [Usage Suggestions](#usage-suggestions)
+1. [Limitations](#limitations)
+
+## Overview
+
+Dockershell can be used as a user login shell, or simply run on the CLI. It
+will stand up a Docker container and then drop the user into a bash shell
+on the container. It's highly configurable and supports multiple profiles.
+
+Note: When combined with my [Abalone](https://github.com/binford2k/abalone) web
+terminal project, this allows you to expose Docker-backed shells to a web browser.
+See [usage suggestions](#usage-suggestions) below.
+
+## Configuration
+
+The configuration is always loaded from `/etc/dockershell/config.yaml`. For security
+purposes, this location is not relocatable or configurable. Sensible defaults are
+provided, so configuration is not strictly required.
+
+* `:loglevel`
+    * Standard log levels: `:fatal`, `:error`, `:warn`, `:info`, `:debug`
+    * Default value: `:warn`
+* `:logfile`
+    * Where you want to log to.
+    * Default value: `/var/log/dockershell`
+*  `:domain`
+    * The domain to use for container FQDNs
+    * Default value: the domain of the host.
+* `:docker`
+    * A `Hash` of Docker settings.
+    * `:group`
+        * The group allowed to access Docker containers.
+        * Default value: `docker`
+    * `:ipaddr`
+        * The address of the Docker network interface.
+        * Default value: the address of interface `docker0`
+    
+#### Example:
+
+``` yaml
+---
+:loglevel: :warn
+:logfile: /var/log/dockershell
+:domain: try.puppet.com
+:docker:
+    :group: docker
+    :ipaddr: 1.2.3.4
+```
+
+### Profiles
+
+Profiles are how you configure different ways to run the shell. Without a profile,
+Dockershell will simply log you into a new container and destroy it when you log
+out. By defining a profile, you can specify the container name and a series of
+scripts that you can use to configure the container.
+
+Each key of the `:profiles` hash should be the name of a profile. In the following
+example, two profiles (`learn` and `docs`) are defined:
+
+
+``` Yaml
+---
+:profiles:
+    :learn:
+      :image: agent
+      :prerun: pe_classify
+      :setup: course_selector
+      :postrun: pe_purge
+    :docs:
+      :image: agent
+```
+
+Each profile has a number of options you can configure. None have default values.
+
+* `:image`
+    * The name of the Docker image to run.
+    * Required.
+* `:prerun`
+    * The name of a script to run before the container is created.
+*  `:setup`
+    * A script to run after the container is started, but before the user is logged in.
+*  `:postrun`
+    * The cleanup script to run after the session has ended. It is run in a detached
+      process so that it's guaranteed to complete even if the shell is killed.
+    * *This will not execute if the shell is terminated with signal 9 (`SIGKILL`)!*
+
+Each script should exist in `/etc/dockershell/scripts`. A few defaults are provided
+directly in the gem. The script is executed with two values passed:
+
+1. `ARGV[0]` is the FQDN of the container node.
+    * The first segment will be the name of the container.
+1. `ARGV[1]` is the value of the optional `--option` parameter.
+
+#### Built in scripts:
+
+* `pe_classify` will pin the container to a new environment group in the PE Console.
+    * An environment directory is created on disk if needed.
+* `pe_purge` will remove the container from the Puppet Enterprise infrastructure.
+    * The environment directory is removed.
+    * The environment node group is removed.
+    * The node's certificate is cleaned.
+    * The node is purged from PuppetDB.
+* `course_selector` will classify the new node with the name of a Puppet Education course.
+    * Pass the course name to Dockershell with `--option`
+    
+
+## Usage Suggestions
+
+When combined with my [Abalone](https://github.com/binford2k/abalone) web
+terminal project, this allows you to expose Docker-backed shells to a web
+browser. The Abalone configuration could look like:
+
+``` yaml
+---
+:port: 9000
+:bind: 0.0.0.0
+:logfile: /var/log/abalone
+:bannerfile: /etc/dockershell/banner
+:command: /usr/local/bin/dockershell
+:timeout: 900
+:ttl: 60
+:params: ['profile', 'option']
+```
+
+If you prefer to be more prescriptive, you can specify allowed values for
+parameters, such as:
+
+``` yaml
+:params:
+  profile:
+    :values: ['learn', 'docs']
+  option:
+    :values:
+      - default
+      - hiera
+      - parser
+      - testing
+```
+
+Then you would simply load the web terminal with a URL such as:
+http://login.example.com:9000/?profile=learn&option=parser
+
+
+## Limitations
+
+This is super early in development and has not yet been battle tested.
+
+
+## Disclaimer
+
+I take no liability for the use of this tool.
+
+Contact
+-------
+
+binford2k@gmail.com

data/bin/dockershell

@@ -0,0 +1,65 @@
+#! /usr/bin/env ruby
+
+require 'rubygems'
+require 'optparse'
+require 'yaml'
+require 'logger'
+
+require 'facter'
+
+require 'dockershell'
+
+config  = '/etc/dockershell/config.yaml'
+options = {
+  :loglevel => 'info',
+  :logfile  => '/var/log/dockershell',
+  :domain   => Facter.value(:domain),
+  :docker   => {
+    :group  => 'docker',
+    :ipaddr => Facter.value(:ipaddress_docker0),
+  },
+  :profile  => {
+    :image  => 'agent',
+  }
+}
+options.merge!(YAML.load_file(config)) if File.file? config
+options[:logger] = Logger.new(options[:logfile])
+options[:logger].level = Logger::const_get(options[:loglevel].upcase)
+
+optparse = OptionParser.new { |opts|
+    opts.banner = "Usage : dockershell [-p <profile>] [-n <name>] [-d]
+         -- Starts a shell by running a Docker container.
+
+"
+
+    opts.on("-d", "--debug", "Display or log debugging messages") do
+        options[:logger].level = Logger::DEBUG
+    end
+
+    opts.on("-n NAME", "--name NAME", "Provide a name for your container.") do |arg|
+        options[:name] = arg
+    end
+
+    opts.on("-p PROFILE", "--profile PROFILE", "Which profile to start. Defaults to 'default'.") do |arg|
+        next unless options.include? :profiles
+        next unless options[:profiles].include? arg.to_sym
+        options[:profile] = options[:profiles][arg.to_sym]
+    end
+
+    opts.on("-o OPTION", "--option OPTION", "Pass a custom option for prerun/setup/postrun tasks.") do |arg|
+        options[:option] = arg
+    end
+
+    opts.separator('')
+
+    opts.on("-h", "--help", "Displays this help") do
+        puts
+        puts opts
+        puts
+        exit
+    end
+}
+optparse.parse!
+options.delete :profiles
+
+Dockershell.new(options).run!

data/lib/dockershell/wordgen.rb

@@ -0,0 +1,4 @@
+class Dockershell::Wordgen
+
+
+end

data/lib/dockershell.rb

@@ -0,0 +1,133 @@
+require 'json'
+require 'open3'
+
+class Dockershell
+  def initialize(options)
+    @options = options
+    @logger  = options[:logger]
+    @gempath = File.expand_path('..', File.dirname(__FILE__))
+
+    @options[:name] ||= wordgen
+    @options[:fqdn] ||= "#{@options[:name]}.#{@options[:domain]}"
+    @options[:profile][:volumes] ||= []
+
+    @logger.formatter = proc do |severity, datetime, progname, msg|
+      "#{datetime} #{severity.ljust(5)} [#{@options[:name]}] #{msg}\n"
+    end
+  end
+
+  def run!
+    at_exit do
+      detached_postrun
+    end
+    prerun
+    create unless running?
+    setup
+    start
+  end
+
+  def start
+    @logger.info 'starting Dockershell.'
+    args = 'docker', 'exec', '-it', @options[:name], 'script', '-qc', 'bash', '/dev/null'
+    bomb 'could not start container.' unless system(*args)
+  end
+
+  [:prerun, :setup, :postrun].each do |task|
+	  define_method(task) do
+      return unless @options[:profile].include? task
+      script = which(@options[:profile][task]) || return
+  	  @logger.debug "#{task}: #{script} #{@options[:fqdn]} #{@options[:option]}"
+
+  	  # This construct allows us to have an optional 2nd parameter to the script
+      output, status = Open3.capture2e(*[script, @options[:fqdn], @options[:option]].compact)
+      @logger.debug output
+      bomb "#{task} task '#{script} #{@options[:name]} #{@options[:option]}' failed." unless status.success?
+  	end
+  end
+
+  # This spawns a detached process to clean up. This is so it doesn't die when the parent is killed
+  def detached_postrun
+    @logger.info 'terminating and cleaning up.'
+    cleaner = Process.fork do
+      Process.setsid
+
+      output, status = Open3.capture2e('docker', 'kill', @options[:name])
+      @logger.debug output
+      @logger.warn 'could not stop container' unless status.success?
+
+      output, status = Open3.capture2e('docker', 'rm', '-f', @options[:name])
+      @logger.debug output
+      @logger.warn 'could not remove container' unless status.success?
+
+      postrun
+    end
+    Process.detach cleaner
+  end
+
+private
+  def running?
+    data = `docker ps -a`.split("\n")
+    data.shift # remove column header
+
+    names = data.map { |line| line.split.last }
+    if names.include? @options[:name]
+      output, status = Open3.capture2e('docker', 'inspect', @options[:name])
+      bomb 'could not get container info.' unless status.success?
+
+      info = JSON.parse(output)
+      bomb 'multiple containers with this name exist.' unless info.size == 1
+
+      info = info.first
+      @logger.debug(info['State'].inspect)
+
+      bomb 'Inconsistent Docker state.' unless info['State']['Running']
+      true
+    else
+      false
+    end
+  end
+
+  def create
+    @logger.info 'creating container.'
+    args = [
+      'docker', 'run',
+      '--security-opt', 'seccomp=unconfined',
+      '--stop-signal=SIGRTMIN+3',
+      '--tmpfs', '/tmp', '--tmpfs', '/run',
+      '--volume', '/sys/fs/cgroup:/sys/fs/cgroup:ro',
+      '--hostname', "#{@options[:fqdn]}",
+      '--name', @options[:name],
+      "--add-host=puppet:#{@options[:docker][:ipaddr]}",
+      '--expose=80', '-Ptd',
+    ]
+
+    @options[:profile][:volumes].each do |volume|
+      args << '--volume' << volume
+    end
+
+    args << @options[:profile][:image] << '/sbin/init'
+
+    output, status = Open3.capture2e(*args)
+    @logger.debug output
+    bomb 'could not create container.' unless status.success?
+  end
+
+  def bomb(message)
+    @logger.warn message
+    raise "[#{@options[:name]}] #{message}"
+  end
+
+  def which(name)
+    ["/etc/dockershell/scripts/#{name}", "#{@gempath}/scripts/#{name}"].each do |path|
+      return path if File.file? path and File.executable? path
+    end
+    nil
+  end
+
+  def wordgen
+    words = File.readlines("#{@gempath}/resources/places.txt").each { |l| l.chomp! }
+
+    "#{words.sample}-#{words.sample}"
+  end
+
+end