Find file History
Fetching latest commit…
Cannot retrieve the latest commit at this time.
Failed to load latest commit information.


= 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 or get those Lisp guys off your back.  You know the ones I mean.

== 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, especially before
authentication is implemented.

== Installation

You can install via rubygems,

  gem install live_console

or plain old setup.rb:

  ruby setup.rb install

== 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 = :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 = :unix_socket, :path => '/tmp/live-console.sock'
	# As above:

	# Have a LiveConsole run code in a binding other than the top-level:
	lc = :unix_socket, :path => '/tmp/live-console.sock'
	                     :bind => binding
	# 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:

Have a look at doc/lc_example.rb or doc/lc_unix_example.rb for brief examples
of how to use LiveConsole.

Try just running it:

	$ ruby doc/lc_example.rb 4000 test
	# Then, in a different shell:
	$ netcat localhost 4000
	irb(main):001:0> puts 'Wow, magic!'

	$ ruby doc/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 Readline
support.  For this, 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 .  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.

For TCP connections, there is no authentication support yet, although it is
planned for the near future.  This creates a security risk:  anyone that can
connect to the socket can run arbitrary Ruby code as the user who owns the
process.  In fact, even binding to localhost can be a security issue if you're
on a box with any untrusted users.  If there's a chance you don't know what
you're doing, avoid using this library.  The Unix Domain Socket version is more
secure, as you can control access via filesystem permissions.

Only one client can connect at a time.  I don't think anyone needs multiple LC
connections to serve multiple instances of IRB to various clients, but if you
need it, let me know.

The README contains a slur against Lisp guys.  Please stop hitting me with that PDP-10 manual.  I love your language and the lambda tattoo on your chest.  

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

Pete Elmore, author -- (pete.elmore(a)

Roger D. Pack ( provided patches and Windows

== Home page