LiveConsole, a Ruby gem for providing IRB over things other than stdio.
|bin||Cleanup in preparation for a new release.|
|examples||Make example scripts executable. Prepare gemspec for release.|
|lib||Add option to pass init block for each console session|
|LICENSE||Fix whitespace errors|
|README||Prepare for release|
|live_console.gemspec||Make example scripts executable. Prepare gemspec for release.|
= LiveConsole == Summary LiveConsole is a library for providing IRB over a TCP connection or a Unix Domain Socket. If you add it to your application, you can run arbitrary code against your application. For example, you can: * Inspect the state of a running application * Change the state of the application * Patch code on the fly, without a restart. * Let anyone on the net 0wn you if you bind to a public interface. :) It's useful as a diagnostic tool, a debugging tool, and a way to impress your friends. == Stern Security Warning. Grrr. Have a look at the bugs section. It should be pretty apparent that incorrect use of this library could create a large security hole. == Installation You can install via rubygems, gem install live_console == How to use LiveConsole LiveConsole is very easy to use in your own app: require 'rubygems' require 'live_console' # Create a LiveConsole using TCP on port 1337 lc = LiveConsole.new :socket, :port => 1337 # We're not yet accepting connections. We need to start it up: lc.start # Starts the LiveConsole thread # At this point, users can connect and get an IRB prompt. lc.stop # Kills the LiveConsole thread # Now, no one can connect. # Create a LiveConsole using a Unix socket in /tmp/live-console.sock lc = LiveConsole.new :unix_socket, :path => '/tmp/live-console.sock' # As above: lc.start lc.stop # Have a LiveConsole run code in a binding other than the top-level: lc = LiveConsole.new :unix_socket, :path => '/tmp/live-console.sock' :bind => binding lc.start # That will start IRB in the current binding. There is also an accessor: lc.bind = binding # Of course, you must restart before IRB will see the new binding: lc.restart Have a look at examples/lc_example.rb or examples/lc_unix_example.rb for brief examples of how to use LiveConsole. Try just running it: $ ruby examples/lc_example.rb 4000 test # Then, in a different shell: $ netcat localhost 4000 irb(main):001:0> puts 'Wow, magic!' $ ruby examples/lc_unix_example.rb /tmp/live-console.sock # Then, in a different shell: $ udscat /tmp/live-console.sock irb(main):001:0> puts 'Words cannot describe the joy I feel.' You can get creative about it, only starting LiveConsole when there's an unhandled exception in your server, and then calling LiveConsole#stop when you've diagnosed and fixed whatever the problem was. Additionally, if you want to run LiveConsole on a server, but run netcat locally, you can use SSH port forwarding to avoid having to open LiveConsole to the world: ssh -L4000:localhost:4000 you@server Then, locally, you can do netcat localhost 4000 and get the remote LiveConsole. man ssh for more details. Of course, this only works for the TCP socket mode. == Bugs LiveConsole lacks many of the niceties of IRB on the console, like full Readline support. LiveConsole does offer tab completion if you write a client that sends the phrase to complete, ending with a tab and newline. LiveConsole will activate the IRB completion proc and send back the results, terminated by newline. Readline history support can be added if anyone finds it useful to manage history remotely. For full Readline support, you can actually use the wonderful rlwrap program, which wraps an arbitrary interactive program in readline. For example, to connect to a LiveConsole on localhost:3333, use rlwrap netcat localhost 3333 rlwrap is available with most Linux distributions or at http://utopia.knoware.nl/~hlub/uck/rlwrap/ . It is seriously an incredibly useful piece of software. Typing exit, hitting ^D, or sending signals (like INT or STOP) doesn't work. Just exit the program you used to connect to it. This has more to do with the program you use to connect to the socket. Other than that, LiveConsole doesn't have any known bugs, but it is odd software that also monkey-patches IRB, so they are likely to be there. Bug reports and patches gratefully accepted. == Credits Jennifer Hickey, project owner -- (jencompgeek(a)gmail.com) Pete Elmore, original author -- (pete.elmore(a)gmail.com) Roger D. Pack (http://betterlogic.com/roger/) provided patches and Windows support