trinidad_jmx_remote_extension 0.1.0

data/.gitignore

@@ -0,0 +1,9 @@
+*.gem
+*.rbc
+.bundle
+Gemfile.lock
+coverage
+doc/
+lib/bundler/man
+pkg
+rdoc

data/Gemfile

@@ -0,0 +1,3 @@
+source 'https://rubygems.org'
+# Specify your gem's dependencies in trinidad_jmx_remote_extension.gemspec
+gemspec

data/LICENSE

@@ -0,0 +1,20 @@
+Copyright (c) 2012 kares
+
+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,87 @@
+# Trinidad JMX Remote Extension
+
+This extension allows you to enable remote JMX (Java Management Extensions) 
+monitoring capabilities for [Trinidad](https://github.com/trinidad/trinidad/).
+
+The extension sets up a Tomcat lifecycle listener which fixes the ports used by
+JMX/RMI to static ones (known ahead of time) thus making things much simpler if
+you need to connect [JConsole](http://bit.ly/jconsole) or any similar tool to a
+remote Trinidad instance running behind a firewall.
+
+Please note that only the ports are configured via the listener, the remainder 
+of the configuration is via the standard system properties for configuring JMX. 
+
+## Install
+
+Along with Trinidad in your application's *Gemfile*:
+
+```ruby
+  group :server do
+    platform :jruby do
+      gem 'trinidad', :require => false
+      gem 'trinidad_jmx_remote_extension', :require => false
+    end
+  end
+```
+
+And then execute:
+
+    $ bundle
+
+Or install it yourself as:
+
+    $ gem install trinidad_jmx_remote_extension
+
+## Setup
+
+Like all extensions it is setup in the configuration file e.g. *trinidad.yml* :
+
+```yaml
+---
+  # ...
+  extensions:
+    jmx_remote:
+      useLocalPorts: true # bind to localhost than setup a ssh tunnel
+      # assuming you'll setup the tunnel you shall remember these ports :
+      rmiRegistryPortPlatform: 9993
+      rmiServerPortPlatform: 9994
+```
+
+Now your server should be setup, do not forget to restart Trinidad ... You might
+want to disable JMX authentication (at first) and set the RMI hostname e.g. by :
+
+    $ jruby -J-Dcom.sun.management.jmxremote.ssl=false -J-D-Dcom.sun.management.jmxremote.authenticate=false -J-Djava.rmi.server.hostname=<trinidad-host-name> -S trinidad -e production
+
+Next you will need to make sure you can SSH into the remote machine locally.
+
+### Local Setup
+
+SSH tunnel (those ports) into the machine where Trinidad is running :
+
+    $ ssh -N -L9993:localhost:9993 -L9994:localhost:9994 user@remotehost
+
+Download the *catalina-jmx-remote.jar* into your current working directory :
+
+    $ wget http://archive.apache.org/dist/tomcat/tomcat-7/v7.0.30/bin/extras/catalina-jmx-remote.jar
+
+You shall use the same *catalina-jmx-remote.jar* locally as the extension is 
+using on the remote Trinidad machine, this guide reflects the .jar distributed 
+with the latest version of the gem. When in doubt simply `gem install` the same
+version locally and copy the .jar from the unpacked gem e.g. using :
+
+    $ jruby -rubygems -e "require 'trinidad_jmx_remote_extension'; puts Trinidad::Extensions::JmxRemote::JAR_PATH"
+
+Now open `jconsole`, assuming your JMX connection string looks like this :
+**service:jmx:rmi://localhost:9994/jndi/rmi://localhost:9993/jmxrmi**
+
+    $ jconsole -debug -J"-Djava.class.path=$JAVA_HOME/lib/tools.jar:$JAVA_HOME/lib/jconsole.jar:catalina-jmx-remote.jar" service:jmx:rmi://localhost:9994/jndi/rmi://localhost:9993/jmxrmi
+
+This is assuming a standard JDK installation (non Apple Java) ...
+
+For more details, this guide has been inspired by the following excellent post :
+http://danielkunnath.com/post/9969130766/dancing-with-jmx-jconsole-tomcat-6-ssh
+
+## Copyright
+
+Copyright (c) 2012 [Karol Bucek](https://github.com/kares).
+See LICENSE (http://en.wikipedia.org/wiki/MIT_License) for details.

data/Rakefile

@@ -0,0 +1,32 @@
+#!/usr/bin/env rake
+require "bundler/gem_tasks"
+
+jar_path = 'lib/catalina-jmx-remote.jar'
+
+desc "update (bundled) catalina-jmx-remote.jar"
+task :update_jar, :version do |_, args| # e.g. `rake update_jar[7.0.30]`
+  require 'open-uri'; require 'fileutils'
+  uri_start = 'http://archive.apache.org/dist/tomcat/tomcat-7/'
+  uri_end = '/bin/extras/catalina-jmx-remote.jar'
+  jar_file = open(uri = "#{uri_start}v#{args[:version]}#{uri_end}",'rb')
+  Rake::Task['remove_jar'].invoke
+  File.open(jar_path, 'wb') { |file| file.write jar_file.read }
+  # and update README section to match the same .jar :
+  readme = File.expand_path('README.md', File.dirname(__FILE__))
+  old_uri = /#{Regexp.escape(uri_start)}v.*?#{Regexp.escape(uri_end)}/
+  lines = IO.readlines(readme).map { |line| line.gsub(old_uri, uri) }
+  File.open(readme, 'w') { |file| file.write(lines.join) }
+end
+
+task :remove_jar do
+  File.delete jar_path if File.exist? jar_path
+end
+
+require 'rake/testtask'
+Rake::TestTask.new do |t|
+  t.libs << "test"
+  t.test_files = FileList['test/*test.rb']
+  t.verbose = true
+end
+
+task :default => :test

data/lib/trinidad_jmx_remote_extension.rb

@@ -0,0 +1,28 @@
+require 'trinidad'
+require "trinidad_jmx_remote_extension/version"
+
+module Trinidad
+  module Extensions
+    module JmxRemote
+      unless const_defined?(:JAR_PATH)
+        JAR_PATH = File.expand_path('catalina-jmx-remote.jar', File.dirname(__FILE__))
+      end
+    end
+    class JmxRemoteServerExtension < ServerExtension
+
+      def configure(tomcat)
+        load JmxRemote::JAR_PATH
+        listener = Java::OrgApacheCatalinaMbeans::JmxRemoteLifecycleListener.new
+        options.each do |key, value| # e.g. useLocalPorts: true
+          if listener.respond_to? method = "set#{key.to_s.upcase}"
+            listener.send(method, value)
+          elsif listener.respond_to? method = "#{key}="
+            listener.send(method, value)
+          end
+        end
+        tomcat.server.add_lifecycle_listener listener
+      end
+      
+    end
+  end
+end

data/lib/trinidad_jmx_remote_extension/version.rb

@@ -0,0 +1,7 @@
+module Trinidad
+  module Extensions
+    module JmxRemote
+      VERSION = "0.1.0"
+    end
+  end
+end

data/test/test_helper.rb

@@ -0,0 +1,13 @@
+begin
+  require 'bundler/setup'
+rescue LoadError
+  require 'rubygems'
+  require 'bundler/setup'
+end
+Bundler.require(:default)
+
+require 'test-unit'
+
+require "trinidad"
+
+$:.unshift(File.dirname(__FILE__) + '/../lib')

data/test/trinidad.yml

@@ -0,0 +1,9 @@
+---
+  environment: production
+  port: 4444
+  trap: false
+  extensions:
+    jmx_remote:
+      useLocalPorts: true
+      rmiRegistryPortPlatform: 9993
+      rmiServerPortPlatform: 9994

data/test/trinidad_jmx_remote_extension_test.rb

@@ -0,0 +1,37 @@
+require File.expand_path('test_helper', File.dirname(__FILE__))
+require 'yaml'
+
+module Trinidad
+  module Extensions
+    class JmxRemoteServerExtensionTest < Test::Unit::TestCase
+      
+      test "loads jar and configures listener" do
+        config = File.expand_path('trinidad.yml', File.dirname(__FILE__))
+        options = YAML.load( File.read(config) )
+        config = Trinidad.configure!(options)
+        Trinidad::Extensions.configure_server_extensions(config[:extensions], tomcat)
+        
+        begin
+          Java::OrgApacheCatalinaMbeans::JmxRemoteLifecycleListener
+        rescue NameError => e
+          flunk "failed loading classes from catalina-jmx-remote.jar #{e.inspect}"
+        end
+        
+        listeners = tomcat.server.find_lifecycle_listeners
+        assert listeners.size > 0
+        assert_kind_of org.apache.catalina.mbeans.JmxRemoteLifecycleListener, listeners[0]
+        assert_true listeners[0].use_local_ports?
+        
+        assert_equal 9993, listeners[0].rmi_registry_port_platform
+        assert_equal 9994, listeners[0].rmi_server_port_platform
+      end
+      
+      private
+
+      def tomcat
+        @tomcat ||= org.apache.catalina.startup.Tomcat.new
+      end
+      
+    end
+  end
+end

data/trinidad_jmx_remote_extension.gemspec

@@ -0,0 +1,29 @@
+# -*- encoding: utf-8 -*-
+$:.push File.expand_path("../lib", __FILE__)
+require "trinidad_jmx_remote_extension/version"
+
+Gem::Specification.new do |gem|
+  gem.name          = "trinidad_jmx_remote_extension"
+  gem.version       = Trinidad::Extensions::JmxRemote::VERSION
+  
+  gem.description   = %q{JMX Remote Extension for Trinidad}
+  gem.summary       = %q{The extension sets up a Tomcat lifecycle listener
+  which fixes the port used by JMX/RMI to static ones known ahead of time thus 
+  making things much simpler if you need to connect JConsole or similar to a 
+  remote Trinidad instance running behind a firewall (e.g. via SSH).}
+  
+  gem.authors       = ["Karol Bucek"]
+  gem.email         = ["self@kares.org"]
+  gem.homepage      = 'http://github.com/kares/trinidad_jmx_remote_extension'
+
+  gem.files         = `git ls-files`.split("\n")
+  gem.test_files    = `git ls-files -- {test}/*`.split("\n")
+  
+  gem.rdoc_options = ["--charset=UTF-8"]
+  gem.extra_rdoc_files = %w[ README.md LICENSE ]
+  
+  gem.require_paths = ["lib"]
+  gem.add_dependency('trinidad', '>= 1.3.5')
+  gem.add_development_dependency('rake')
+  gem.add_development_dependency('test-unit', '>= 2.4')
+end

metadata

@@ -0,0 +1,99 @@
+--- !ruby/object:Gem::Specification 
+name: trinidad_jmx_remote_extension
+version: !ruby/object:Gem::Version 
+  prerelease: 
+  version: 0.1.0
+platform: ruby
+authors: 
+  - Karol Bucek
+autorequire: 
+bindir: bin
+cert_chain: []
+
+date: 2012-10-09 00:00:00 Z
+dependencies: 
+  - !ruby/object:Gem::Dependency 
+    name: trinidad
+    prerelease: false
+    requirement: &id001 !ruby/object:Gem::Requirement 
+      none: false
+      requirements: 
+        - - ">="
+          - !ruby/object:Gem::Version 
+            version: 1.3.5
+    type: :runtime
+    version_requirements: *id001
+  - !ruby/object:Gem::Dependency 
+    name: rake
+    prerelease: false
+    requirement: &id002 !ruby/object:Gem::Requirement 
+      none: false
+      requirements: 
+        - - ">="
+          - !ruby/object:Gem::Version 
+            version: "0"
+    type: :development
+    version_requirements: *id002
+  - !ruby/object:Gem::Dependency 
+    name: test-unit
+    prerelease: false
+    requirement: &id003 !ruby/object:Gem::Requirement 
+      none: false
+      requirements: 
+        - - ">="
+          - !ruby/object:Gem::Version 
+            version: "2.4"
+    type: :development
+    version_requirements: *id003
+description: JMX Remote Extension for Trinidad
+email: 
+  - self@kares.org
+executables: []
+
+extensions: []
+
+extra_rdoc_files: 
+  - README.md
+  - LICENSE
+files: 
+  - .gitignore
+  - Gemfile
+  - LICENSE
+  - README.md
+  - Rakefile
+  - lib/catalina-jmx-remote.jar
+  - lib/trinidad_jmx_remote_extension.rb
+  - lib/trinidad_jmx_remote_extension/version.rb
+  - test/test_helper.rb
+  - test/trinidad.yml
+  - test/trinidad_jmx_remote_extension_test.rb
+  - trinidad_jmx_remote_extension.gemspec
+homepage: http://github.com/kares/trinidad_jmx_remote_extension
+licenses: []
+
+post_install_message: 
+rdoc_options: 
+  - --charset=UTF-8
+require_paths: 
+  - lib
+required_ruby_version: !ruby/object:Gem::Requirement 
+  none: false
+  requirements: 
+    - - ">="
+      - !ruby/object:Gem::Version 
+        version: "0"
+required_rubygems_version: !ruby/object:Gem::Requirement 
+  none: false
+  requirements: 
+    - - ">="
+      - !ruby/object:Gem::Version 
+        version: "0"
+requirements: []
+
+rubyforge_project: 
+rubygems_version: 1.8.15
+signing_key: 
+specification_version: 3
+summary: The extension sets up a Tomcat lifecycle listener which fixes the port used by JMX/RMI to static ones known ahead of time thus  making things much simpler if you need to connect JConsole or similar to a  remote Trinidad instance running behind a firewall (e.g. via SSH).
+test_files: []
+