lumberg 1.0.1 → 2.0.0.pre4

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA1:
+  metadata.gz: 8729386fae62f1240d8ca35e0b2440a5c13fd121
+  data.tar.gz: 0da476df19735bf334e8addb63f6507e1946a6be
+SHA512:
+  metadata.gz: 48a7cf27c6d95dd99e2fe3553f8c91fe12a96a58996c38f0058997131798d55b5c317876a255d04059d586b36386a35cf3ba1749529766bfadf7f209681be0b7
+  data.tar.gz: ec675a24333fa0ba2b7e6070959c57eb7663a4df9b7a351818ecb5a165e50f7a20ce5e0a53a6818cddefaacc819e99d8f2eb0ce9b7d2f18656948d7becef927c

data/.travis.yml

@@ -1,11 +1,12 @@
+language: ruby
 script: "bundle exec rake spec"
 notifications:
-  disabled: true
+  email:
+    recipients:
+      - engineering@internal.site5.com
+    on_success: never
+    on_failure: always
 rvm:
-  - 1.8.7
-  - 1.9.2
   - 1.9.3
-  - ree
-  - rbx
-  - rbx-head
-  - jruby
+  - 2.0.0
+  - jruby-19mode

data/LICENSE

@@ -1,4 +1,4 @@
-Copyright (c) 2011 Site5 LLC 
+Copyright (c) 2012 Site5.com <http://www.site5.com>
 
 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,21 +7,19 @@ 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
+Confirmed to work with ruby 1.8.7, 1.9.2, REE and JRuby 1.6.0 on
 cPanel 11.28+
 
 [Build Status]: http://travis-ci.org/site5/lumberg
 [Build Icon]: https://secure.travis-ci.org/site5/lumberg.png?branch=master
 
 
-Install
--------
+## Install
 
     gem install lumberg
 
 
-Usage
------
+## Usage
 
 Create a server object and connect to WHM using your host and hash:
 
@@ -108,8 +105,7 @@ pp result[:params][:acct].first
 ```
 
 
-Account Example
----------------
+### Account Example
 
 Creating a new account requires only a username, domain, and password.
 
@@ -168,8 +164,7 @@ 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.
@@ -218,20 +213,133 @@ 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.
 
-Note on Patches/Pull Requests
-=============================
 
-All HTTP interactions are recorded using VCR and FakeWeb. Please be sure to
-remove any sensitive information from your cassettes.
+#### 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
+)
+
+# 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 unwiedly; 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.).
+
+### 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
   future version unintentionally.
@@ -240,7 +348,6 @@ remove any sensitive information from your cassettes.
   commit by itself I can ignore when I pull)
 * Send me a pull request. Bonus points for topic branches.
 
-Copyright
-=========
+## Copyright
 
-Copyright (c) 2011 Site5. See LICENSE for details.
+Copyright (c) 2012-2013 Site5.com. 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

data/lib/lumberg/cpanel/contact.rb

@@ -0,0 +1,38 @@
+module Lumberg
+  module Cpanel
+    # Public: Allows users to specify contact information and preferences
+    class Contact < Base
+      def self.api_module; "CustInfo"; end
+
+      # Public: Show your contact information and email notfication settings
+      #
+      # Returns Hash API response
+      def show
+        perform_request({ :api_function => 'displaycontactinfo' })
+      end
+
+      # Public: Updates the user's contact info and settings for email
+      # notifications
+      #
+      # options - Hash options for API call params (default: {})
+      #   :email - String email account to send notifications to
+      #   :second_email - String secondary email account to send notifications
+      #                   to (default: String)
+      #   :email_quota - Boolean value. Set to true to be notified when you are
+      #                  when one of your email accounts approaches or is over
+      #                  quota (default: Boolean)
+      #   :disk_quota - Boolean value. Set to true to be notified when you are
+      #                 when you are reaching your disk quota (default: Boolean)
+      #   :bandwidth - Boolean value. Set to true to be notified when you are
+      #                reaching your bandwidth usage limit (default: Boolean)
+      #
+      # Returns Hash API response
+      def update(options = {})
+        options[:notify_disk_limit] = options.delete(:disk_quota)
+        options[:notify_bandwidth_limit] = options.delete(:bandwidth)
+        options[:notify_email_quota_limit] = options.delete(:email_quota)
+        perform_request({ :api_function => 'savecontactinfo' }.merge(options))
+      end
+    end
+  end
+end

data/lib/lumberg/cpanel/cron.rb

@@ -0,0 +1,89 @@
+module Lumberg
+  module Cpanel
+    class Cron < Base
+      # Public: Set default cron notification email address.
+      #
+      # options - Hash options for API call params (default: {}):
+      #  :email - String email address to receive notifications.
+      #
+      # Returns Hash API response.
+      def set_email(options = {})
+        perform_request({
+          :api_function => "set_email"
+        }.merge(options))
+      end
+
+      # Public: Get the default cron notification email address.
+      #
+      # options - Hash options for API call params (default: {})
+      #
+      # Returns Hash API response.
+      def email(options = {})
+        perform_request({
+          :api_function => "get_email"
+        }.merge(options))
+      end
+
+      # Public: Get list of cron jobs.
+      #
+      # options - Hash options for API call params (default: {})
+      #
+      # Returns Hash API response.
+      def list(options = {})
+        perform_request({
+          :api_function => "listcron"
+        }.merge(options))
+      end
+
+      # Public: Add a cron job.
+      #
+      # options - Hash options for API call params (default: {}):
+      #  :command - String command to execute.
+      #  :day     - String day value.
+      #  :hour    - String hour value.
+      #  :minute  - String minute value.
+      #  :month   - String month value.
+      #  :weekday - String weekday value.
+      #
+      # Returns Hash API response.
+      def add(options = {})
+        perform_request({
+          :api_function => "add_line"
+        }.merge(options))
+      end
+
+      # Public: Remove a cron job.
+      #
+      # options - Hash options for API call params (default: {}):
+      #  :linekey - String linekey of the crontab entry to remove.
+      #
+      # Returns Hash API response.
+      def remove(options = {})
+        perform_request({
+          :api_function => "remove_line"
+        }.merge(options))
+      end
+
+      # Public: Edit a crontab entry.
+      #
+      # options - Hash options for API call params (default: {}):
+      #  :command       - String command to execute.
+      #  :day           - String day value.
+      #  :hour          - String hour value.
+      #  :minute        - String minute value.
+      #  :month         - String month value.
+      #  :weekday       - String weekday value.
+      #  :commandnumber - Integer Line of cron entry to edit (optional).
+      #                   If not present, :linekey is required.
+      #  :linekey       - String Linekey for entry to edit (optional).
+      #                   If not present, :commandnumber is required.
+      #
+      # Returns Hash API response.
+      def edit(options = {})
+        perform_request({
+          :api_function => "edit_line"
+        }.merge(options))
+      end
+    end
+  end
+end

data/lib/lumberg/cpanel/dns_lookup.rb

@@ -0,0 +1,23 @@
+module Lumberg
+  module Cpanel
+    class DnsLookup < Base
+      # Public: Basic DNS functionality. This function will return the ip
+      # address associated with a domain. If multiple addresses are associated
+      # with that domain, only one will be returned
+      #
+      # options   - Hash options for API call params (default: {})
+      #   :domain - String domain you wish to lookup
+      #
+      # Examples
+      #   api_args = { host: "x.x.x.x", hash: "pass", api_username: "user" }
+      #   dns_lookup = Lumberg::Cpanel::DnsLookup.new(api_args.dup)
+      #
+      #   dns_lookup.name_to_ip(domain: 'google.com')
+      #
+      # Returns Hash API response.
+      def name_to_ip(options = {})
+        perform_request({ :api_function => 'name2ip' }.merge(options))
+      end
+    end
+  end
+end