lumberg 1.0.1 → 2.0.1

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA1:
+  metadata.gz: a5ccd3bf942f150d835527fa7bfdbf89f8c0e214
+  data.tar.gz: 8f8723d73089a5c80c5fb5c0f6c88b7a92e8d69e
+SHA512:
+  metadata.gz: 7dc50efeb877e113a34c0a92e412503b31b324dddba4ae9d5a4e1517830fd059424b84d8049acab06e9938ae5c465d516ebf17697adf72f6813eb03b615a57f8
+  data.tar.gz: f3daae45a95e11563237514ae66e122b95a474ce7a416ee97dfad144f7fb327c12e232cefc111c854a60c1de3243c58a6a31271e55d733710072379d1452f263

data/LICENSE

@@ -1,4 +1,4 @@
-Copyright (c) 2011 Site5 LLC 
+Copyright (c) 2015 WWWH, LLC.
 
 Permission is hereby granted, free of charge, to any person obtaining
 a copy of this software and associated documentation files (the

data/README.md

@@ -1,5 +1,4 @@
-Lumberg [![Lumberg Build Status][Build Icon]][Build Status]
-===========================================================
+# Lumberg [![Lumberg Build Status][Build Icon]][Build Status]
 
 ![Lumberg logo](http://i.imgur.com/xC4Sw.jpg)
 
@@ -8,29 +7,33 @@ beta-ish. Please report any issues you find. :)
 
 [RDoc](http://rdoc.info/github/site5/lumberg/master/frames)
 
-Confirmed to work with ruby 1.8.7, 1.9.2, Rubinius, REE and JRuby 1.6.0 on
-cPanel 11.28+
+Confirmed to work with ruby 1.9.3, 2.0.0, 2.1.3, 2.2.0 and JRuby 1.9 mode.
 
 [Build Status]: http://travis-ci.org/site5/lumberg
 [Build Icon]: https://secure.travis-ci.org/site5/lumberg.png?branch=master
 
 
-Install
--------
+## cPanel Version Targets
+
+* cPanel 11.4x: _v2.0.0_
+* cPanel 11.3x: _v2.0.0.pre10_
+* cPanel 11.2x: _v1.1.1_
+
+
+## Install
 
     gem install lumberg
 
 
-Usage
------
+## Usage
 
 Create a server object and connect to WHM using your host and hash:
 
 ```ruby
 require 'lumberg'
 server = Lumberg::Whm::Server.new(
-  :host => WHM_HOST,
-  :hash => WHM_HASH
+  host: WHM_HOST,
+  hash: WHM_HASH
 )
 ```
 
@@ -38,9 +41,10 @@ If you are using HTTP Basic Authentication with a username/password:
 
 ```ruby
 server = Lumberg::Whm::Server.new(
-  :host => WHM_HOST,
-  :user => USERNAME,
-  :hash => 'my_password'
+  host:       WHM_HOST,
+  user:       USERNAME,
+  hash:       'my_password',
+  basic_auth: true
 )
 ```
 
@@ -81,43 +85,42 @@ Here's an example of what the returned data looks like for a single account
 pp result[:params][:acct].first
 
 {
-  :startdate=>false,
-  :plan           => "default",
-  :suspended      => false,
-  :theme          => "x3",
-  :shell          => "/usr/local/cpanel/bin/jailshell",
-  :maxpop         => "unlimited",
-  :maxlst         => "unlimited",
-  :maxaddons      => "*unknown*",
-  :suspendtime    => nil,
-  :ip             => false,
-  :maxsub         => "unlimited",
-  :domain         => "bob.com",
-  :maxsql         => "unlimited",
-  :partition      => "home",
-  :maxftp         => "unlimited",
-  :user           => "bob",
-  :suspendreason  => "not suspended",
-  :unix_startdate => false,
-  :diskused       => false,
-  :maxparked      => "*unknown*",
-  :email          => "*unknown*",
-  :disklimit      => "unlimited",
-  :owner          => "root"
+  startdate:      false,
+  plan:           "default",
+  suspended:      false,
+  theme:          "x3",
+  shell:          "/usr/local/cpanel/bin/jailshell",
+  maxpop:         "unlimited",
+  maxlst:         "unlimited",
+  maxaddons:      "*unknown*",
+  suspendtime:    nil,
+  ip:             false,
+  maxsub:         "unlimited",
+  domain:         "bob.com",
+  maxsql:         "unlimited",
+  partition:      "home",
+  maxftp:         "unlimited",
+  user:           "bob",
+  suspendreason:  "not suspended",
+  unix_startdate: false,
+  diskused:       false,
+  maxparked:      "*unknown*",
+  email:          "*unknown*",
+  disklimit:      "unlimited",
+  owner:          "root"
 }
 ```
 
 
-Account Example
----------------
+### Account Example
 
 Creating a new account requires only a username, domain, and password.
 
 ```ruby
 result = server.account.create(
-  :username => 'newuser',
-  :domain   => 'newuser.com',
-  :password => 'password'
+  username: 'newuser',
+  domain:   'newuser.com',
+  password: 'password'
 )
 
 if result[:success]
@@ -130,18 +133,17 @@ Account Creation Ok
 You can list all accounts or search for a specific account.
 
 ```ruby
-result = server.account.list(:search => 'new', :searchtype => 'user')
+result = server.account.list(search: 'new', searchtype: 'user')
 acct   = result[:params][:acct].first
 p "Found user '#{acct[:user]}' with domain '#{acct[:domain]}'"
 
 Found user 'newuser' with domain 'newuser.com'
 ```
 
-
 Suspending an account is simple and the reason for suspension is optional.
 
 ```ruby
-result = server.account.suspend(:username => 'newuser', :reason => 'bad user')
+result = server.account.suspend(username: 'newuser', reason: 'bad user')
 p "user was suspended successfully" if result[:success]
 
 user was suspended successfully
@@ -151,7 +153,7 @@ We can look at the account list again to see the reason for the user's
 suspension.
 
 ```ruby
-result = server.account.list(:search => 'new', :searchtype => 'user')
+result = server.account.list(search: 'new', searchtype: 'user')
 acct   = result[:params][:acct].first
 p "user '#{acct[:user]}' was suspended with reason '#{acct[:suspendreason]}'"
 
@@ -161,28 +163,27 @@ user 'newuser' was suspended with reason 'bad user'
 Finally, we remove the user and delete their account.
 
 ```ruby
-result = server.account.remove(:username => 'newuser')
+result = server.account.remove(username: 'newuser')
 p result[:message]
 
 newuser account removed
 ```
 
 
-Reseller Example
-----------------
+### Reseller Example
 
 Creating a reseller works by changing the status of an existing user account,
 so first we create a user account and then we can create that user as a reseller.
 
 ```ruby
 result = server.account.create(
-  :username => 'rtest',
-  :domain   => 'resellerexample.com',
-  :password => 'password'
+  username: 'rtest',
+  domain:   'resellerexample.com',
+  password: 'password'
 )
 
 if result[:success]
-  result = server.reseller.create(:username => 'rtest', :makeowner => true)
+  result = server.reseller.create(username: 'rtest', makeowner: true)
   p "created reseller rtest" if result[:success]
 end
 
@@ -202,7 +203,7 @@ Suspending a reseller is pretty straightforward. It's optional to provide a
 reason for the suspension.
 
 ```ruby
-result = server.reseller.suspend(:username => 'rtest', :reason => 'bad user')
+result = server.reseller.suspend(username: 'rtest', reason: 'bad user')
 p "reseller was suspended successfully" if result[:success]
 
 user was suspended successfully
@@ -212,35 +213,148 @@ Deleting the reseller removes the reseller status from the user account. To
 also delete the user account, set the `:terminatereseller` argument.
 
 ```ruby
-result = server.reseller.terminate(:reseller => 'rtest', :terminatereseller => true)
+result = server.reseller.terminate(reseller: 'rtest', terminatereseller: true)
 p result[:message]
 
 Account Terminations Complete
 ```
 
-Contributors
-============
+### Accessing cPanel API
 
-* [Justin Mazzi](http://github.com/jmazzi)
-* [Tim Parkin](http://github.com/tparkin)
+[cPanel API](http://docs.cpanel.net/twiki/bin/view/SoftwareDevelopmentKit/ApiIntroduction)
+interface is provided by the `Lumberg::Cpanel` module. Classes within the module
+correspond to cPanel API modules. cPanel API module coverage is currently
+incomplete and we're seeking contributions. Check out [Extending
+Lumberg::Cpanel](#extending-lumbergcpanel) for details on how you can help.
+
+#### Email example
+
+```ruby
+# Create an interface object for cPanel API Email module
+email = Lumberg::Cpanel::Email.new(
+  server:       server,  # An instance of Lumberg::Server
+  api_username: "jerry"  # User whose cPanel we'll be interacting with
+)
 
-Note on Patches/Pull Requests
-=============================
+# Get a list of email accounts
+email.accounts[:params][:data] #=> Array of info hashes for each email account
+
+# Add an email forwarder to forward mail for my-forwarder@domain.com to
+# dest@other-domain.com
+email.add_forwarder(
+  domain:   "domain.com",
+  email:    "my-forwarder",
+  fwdopt:   "fwd",
+  fwdemail: "dest@other-domain.com"
+)
+```
+
+
+## Contributing
+
+### Extending Lumberg::Cpanel
+
+1. Find a cPanel API module that isn't already covered. See
+   [cPanel API documentation](http://docs.cpanel.net/twiki/bin/view/SoftwareDevelopmentKit/ApiIntroduction)
+   for a full list of available API modules.
+
+2. Create a file (underscore style) in `lib/lumberg/cpanel/` named after the
+   cPanel API module you're working on. If the cPanel API module is "LangMods"
+   name the file "lang_mods.rb". You'll define your class here. `require` this
+   file from `lib/lumberg/cpanel.rb`.
+
+3. Define a class that inherits from `Lumberg::Cpanel::Base`:
+   ```ruby
+   # Create a class for (fictional) "SomeModule" API module
+   module Lumberg
+     module Cpanel
+       class SomeModule < Base
+       end
+     end
+   end
+   ```
+   The cPanel API module name is normally inferred from the class name, e.g., if
+   the class name is `Email` the cPanel "Email" API module will be used. If the
+   cPanel API module you're working with doesn't match up with Ruby class naming
+   convention, override the `::api_module` class method:
+   ```ruby
+   module Lumberg
+     module Cpanel
+       class SslInfo
+         def self.api_module; "SSLInfo"; end
+       end
+     end
+   end
+   ```
+4. Fill in the methods.
+   ```ruby
+   module Lumberg
+     module Cpanel
+       class Branding
+         # Public: Get URL locations for specific sprites.
+         #
+         # options - Hash options for API call params (default: {}):
+         #  :img        - String branding object label for the image you want to
+         #                retrieve.
+         #  :imgtype    - String branding image type you want to retrieve, e.g.,
+         #                "icon" or "heading".
+         #  :method     - String specification for returned value options.
+         #                Acceptable values are: "only_filetype_gif",
+         #                "skip_filetype_gif", "snap_to_smallest_width", and
+         #                "scale_60percent".
+         #  :subtype    - String branding image subtype, e.g., "img", "bg",
+         #                "compleximg".
+         #  :image      - String parameter allows you to force appropriate
+         #                output by setting it to "heading" (optional).
+         #  :skipgroups - String parameter allows you to specify whether or not
+         #                to include "img" values that begin with "group_" in
+         #                the output. "1" indicates that you wish to skip "img"
+         #                values that begin with "group_" (optional).
+         #
+         # Returns Hash API response.
+         def list_sprites(options = {})
+           perform_request({
+            api_function: "spritelist"
+           }.merge(options))
+         end
+       end
+     end
+   end
+   ```
+
+   - In many cases, you'll name your methods to match up
+     with the documented cPanel API methods. However, the documented method
+     names are sometimes a bit lengthy, confusing, or otherwise unwieldy; feel
+     free to give your corresponding method an improved name.
+   - Use [TomDoc](http://tomdoc.org/) documentation for your methods.
+     Be sure to document all required and optional parameters from the
+     cPanel API documentation.
+   - All methods should take an options arg that defaults to {}.
+     These options should be merged onto the options passed to
+     #perform_request to allow overriding of :api_username or
+     other parameters.
+
+### Sanitizing VCR cassettes
+
+All HTTP interactions are recorded using VCR and FakeWeb. Please be sure to remove
+sensitive data from your cassettes. A Rake task is provided for this purpose:
+```
+WHM_HOST=my-cpanel-server.com WHM_HASH=$(cat my-access-hash) bundle exec rake sanitize_cassettes
+```
+Once you've sanitized your cassettes, manually verify that there's no sensitive
+information still present (check URLs, authorization params, etc.).
 
-All HTTP interactions are recorded using VCR and FakeWeb. Please be sure to
-remove any sensitive information from your cassettes.
+### Note on Patches/Pull Requests
 
 * Fork the project.
-* Add yourself to the Contributors list
 * Make your feature addition or bug fix.
-* Add tests for it. This is important so I don't break it in a
+* Add tests for it. This is important so we don't break it in a
   future version unintentionally.
-* Commit, do not mess with rakefile, version, or history.
+* Commit, do not mess with Rakefile, version, or history.
   (if you want to have your own version, that is fine but bump version in a
-  commit by itself I can ignore when I pull)
-* Send me a pull request. Bonus points for topic branches.
+  commit by itself we can ignore when we pull)
+* Send us a pull request. Bonus points for topic branches.
 
-Copyright
-=========
+## Copyright
 
-Copyright (c) 2011 Site5. See LICENSE for details.
+Copyright (c) 2015 WWWH, LLC. See LICENSE for details.

data/Rakefile

@@ -14,6 +14,8 @@ begin
 rescue LoadError
 end
 
+load 'vcr/tasks/vcr.rake'
+
 RSpec::Core::RakeTask.new :spec
 Bundler::GemHelper.install_tasks
 
@@ -26,7 +28,7 @@ task :sanitize_cassettes do
       files.each do |file|
         old = File.read(file)
         if old.match(/#{ENV['WHM_HASH']}|#{ENV['WHM_HOST']}/)
-          puts "Sanitizing #{file}" 
+          puts "Sanitizing #{file}"
           old.gsub!(ENV['WHM_HASH'], 'iscool')
           old.gsub!(ENV['WHM_HOST'], 'myhost.com')
           File.open(file, 'w') do |f|

data/lib/lumberg/config.rb

@@ -0,0 +1,19 @@
+module Lumberg
+  # Holds the configuration for Lumberg
+  class Config
+    attr_accessor :options
+
+    def initialize
+      @options = {}
+    end
+
+    def [](v)
+      @options[v]
+    end
+
+    # Debug output.  value can be either true to output to $stderr or a path to a file
+    def debug(output)
+      @options[:debug] = output
+    end
+  end
+end

data/lib/lumberg/cpanel/addon_domain.rb

@@ -0,0 +1,50 @@
+module Lumberg
+  module Cpanel
+    class AddonDomain < Base
+      # Public: Delete an addon domain. This will also remove the corresponding
+      # subdomain and FTP account.
+      #
+      # options - Hash options for API call params (default: {}):
+      #   :domain    - String addon domain to be deleted.
+      #   :subdomain - String adddon domain's username followed by "_", then
+      #                the addon domain's main domain, e.g.,
+      #                "user_addon.com"
+      #
+      # Returns Hash API response.
+      def remove(options = {})
+        perform_request({
+          api_function: "deladdondomain"
+        }.merge(options))
+      end
+
+      # Public: Add an addon domain with a coresponding subdomain.
+      #
+      # options - Hash options for API call params (default: {}):
+      #  :dir       - String path for addon domain docroot.
+      #  :newdomain - String domain to use for addon domain.
+      #  :subdomain - String subdomain / FTP username corresponding to new
+      #               addon domain, e.g., "user".
+      #
+      # Returns Hash API response.
+      def add(options = {})
+        perform_request({
+          api_function: "addaddondomain"
+        }.merge(options))
+      end
+
+      # Public: Get a list of addon domains.
+      #
+      # options - Hash options for API call params (default: {}):
+      #  :regex - String regular expression to filter search results
+      #           (optional).
+      #
+      # Returns Hash API response.
+      def list(options={})
+        perform_request({
+          api_function: "listaddondomains"
+        }.merge(options))
+      end
+    end
+  end
+end
+

data/lib/lumberg/cpanel/backups.rb

@@ -0,0 +1,16 @@
+module Lumberg
+  module Cpanel
+    class Backups < Base
+      # Public: Get a list backups.
+      #
+      # options - Hash options for API call params (default: {})
+      #
+      # Returns Hash API response.
+      def list(options = {})
+        perform_request({
+          api_function: "listfullbackups"
+        }.merge(options))
+      end
+    end
+  end
+end

data/lib/lumberg/cpanel/base.rb

@@ -0,0 +1,56 @@
+module Lumberg
+  module Cpanel
+    class Base < Whm::Base
+      attr_accessor :api_username
+
+      # Public: Gets cPanel API module name based on class name. This method
+      # should be overriden in subclasses where the cPanel API module name
+      # and the class name don't match up.
+      #
+      # Returns String cPanel API module name.
+      def self.api_module
+        self.name.split("::").last
+      end
+
+      # Public: Initialize a new cPanel API interface.
+      #
+      # options - Hash options (default: {}):
+      #   :api_username - String username to set as the default account
+      #                   username for cPanel API calls (optional).
+      def initialize(options = {})
+        @api_username = options.delete(:api_username)
+
+        super options
+      end
+
+      # Public: Perform a cPanel API method call.
+      #
+      # options - Hash options for API call params (default: {}):
+      #   :api_function - String API function name to call.
+      #   :api_module   - String API module on which API function will be
+      #                   called (optional, default: self.class.api_module).
+      #   :response_key - String key used to select desired part of API
+      #                   response (optional, default: "cpanelresult").
+      #   :api_username - String account username for API call (optional,
+      #                   default: @api_username)
+      #   :api_version  - Integer cPanel API version to use (optional,
+      #                   default: 2)
+      #
+      # Returns Hash API response.
+      def perform_request(options = {})
+        options[:api_username] ||= api_username
+
+        api_module = options.delete(:api_module) || self.class.api_module
+        params = {
+          response_key:              options.delete(:response_key) || "cpanelresult",
+          cpanel_jsonapi_user:       options.delete(:api_username),
+          cpanel_jsonapi_module:     api_module,
+          cpanel_jsonapi_func:       options.delete(:api_function),
+          cpanel_jsonapi_apiversion: options.delete(:api_version) || 2,
+        }.merge(options)
+
+        server.perform_request("cpanel", params)
+      end
+    end
+  end
+end

data/lib/lumberg/cpanel/box_trapper.rb

@@ -0,0 +1,18 @@
+module Lumberg
+  module Cpanel
+    class BoxTrapper < Base
+      # Public: Get list of email accounts and their BoxTrapper statuses.
+      #
+      # options - Hash options for API call params (default: {}):
+      #   :regex - String regular expression to filter search results
+      #            (optional).
+      #
+      # Returns Hash API response.
+      def list(options = {})
+        perform_request({
+          api_function: "accountmanagelist"
+        }.merge(options))
+      end
+    end
+  end
+end

data/lib/lumberg/cpanel/branding.rb

@@ -0,0 +1,89 @@
+module Lumberg
+  module Cpanel
+    class Branding < Base
+      # Public: Get list of branding packages.
+      #
+      # options - Hash options for API call params (default: {}):
+      #  :onlyshowyours - Return only packages that the user owns?
+      #                   String "1" or "0" (optional).
+      #  :showroot      - Only return system branding packages?
+      #                   String "1" or "0" (optional).
+      #  :skipglobal    - Only return customized branding packages?
+      #                   String "1" or "0" (optional).
+      #  :skiphidden    - Skip branding packages owned by the user?
+      #                   String "1" or "0" (optional).
+      #
+      # Returns Hash API response.
+      def list_pkgs(options = {})
+        perform_request({
+          api_function: "showpkgs"
+        }.merge(options))
+      end
+
+      # Public: Get URL locations for specific sprites.
+      #
+      # options - Hash options for API call params (default: {}):
+      #  :img        - String branding object label for the image you want to
+      #                retrieve.
+      #  :imgtype    - String branding image type you want to retrieve, e.g.,
+      #                "icon" or "heading".
+      #  :method     - String specification for returned value options.
+      #                Acceptable values are: "only_filetype_gif",
+      #                "skip_filetype_gif", "snap_to_smallest_width", and
+      #                "scale_60percent".
+      #  :subtype    - String branding image subtype, e.g., "img", "bg",
+      #                "compleximg".
+      #  :image      - String parameter allows you to force appropriate
+      #                output by setting it to "heading" (optional).
+      #  :skipgroups - String parameter allows you to specify whether or not
+      #                to include "img" values that begin with "group_" in
+      #                the output. "1" indicates that you wish to skip "img"
+      #                values that begin with "group_" (optional).
+      #
+      # Returns Hash API response.
+      def list_sprites(options = {})
+        perform_request({
+          api_function: "spritelist"
+        }.merge(options))
+      end
+
+      # Public: Retrieve a list of icons within the x3 interface.
+      #
+      # options - Hash options for API call params (default: {}):
+      #  :nvarglist - String parameter allows you to specify the order in
+      #               which you wish to have groups returned, separated by
+      #               pipes, e.g., "mail|files|domains|logs". This is the
+      #               last filter on the data and is stored in your
+      #               xmaingroupsorder NVDATA variable (optional).
+      #
+      # Returns Hash API response.
+      def list_icons(options = {})
+        perform_request({
+          api_function: "applist"
+        }.merge(options))
+      end
+
+      # Public: Get list of branding object types.
+      #
+      # options - Hash options for API call params (default: {}):
+      #
+      # Returns Hash API response.
+      def list_object_types(options = {})
+        perform_request({
+          api_function: "listobjecttypes"
+        }.merge(options))
+      end
+
+      # Public: Get list of branding image types.
+      #
+      # options - Hash options for API call params (default: {}):
+      #
+      # Returns Hash API response.
+      def list_image_types(options = {})
+        perform_request({
+          api_function: "listimgtypes"
+        }.merge(options))
+      end
+    end
+  end
+end