Permalink
Browse files

Documentation updates.

  • Loading branch information...
1 parent 29895d2 commit 344920af87dbad520dac986d6a216320fd31b113 tailor committed Oct 16, 2008
Showing with 58 additions and 32 deletions.
  1. +43 −18 doc/README
  2. +15 −14 lib/live_console.rb
View
@@ -2,15 +2,16 @@
== Summary
-LiveConsole is a library for providing IRB over a TCP connection . If you add
-it to your application, you can run arbitrary code against your application.
+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 anything other than
- localhost. :)
-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.
+ * 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.
@@ -35,21 +36,39 @@ LiveConsole is very easy to use in your own app:
require 'rubygems'
require 'live_console'
- lc = LiveConsole.new 1337 # Creates a LiveConsole on port 1337
+ # 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.run # Starts the LiveConsole thread
+ 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.
-Have a look at doc/lc_example.rb for a brief example of how to use LiveConsole.
+ # 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.bind = binding
+ lc.start
+
+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.
@@ -72,20 +91,26 @@ LiveConsole lacks many of the niceties of IRB on the console, like Readline
support.
Typing exit, hitting ^D, or sending signals (like INT or STOP) doesn't work.
-Just exit the program you used to connect to it.
+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.
-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.
+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 alpha
-software, so they are likely to be there. Bug reports and patches gratefully
-accepted.
+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
View
@@ -9,10 +9,10 @@
# LiveConsole provides a socket that can be connected to via netcat or telnet
# to use to connect to an IRB session inside a running process. It creates a
-# thread that listens on the specified address/port, and presents connecting
-# clients with an IRB shell. Using this, you can execute code on a running
-# instance of a Ruby process to inspect the state or even patch code on the
-# fly. There is currently no readline support.
+# thread that listens on the specified address/port or Unix Domain Socket path,
+# and presents connecting clients with an IRB shell. Using this, you can
+# execute code on a running instance of a Ruby process to inspect the state or
+# even patch code on the fly. There is currently no readline support.
class LiveConsole
include Socket::Constants
autoload :IOMethods, 'live_console/io_methods'
@@ -21,16 +21,17 @@ class LiveConsole
private :io_method=, :io=, :thread=
# call-seq:
- # # Bind a LiveConsole to localhost:3030:
- # LiveConsole.new :socket, :port => 3030
+ # # Bind a LiveConsole to localhost:3030 (only allow clients on this
+ # # machine to connect):
+ # LiveConsole.new :socket, :port => 3030
# # Accept connections from anywhere on port 3030. Ridiculously insecure:
- # LiveConsole.new(:socket, :port => 3030, :host => '0.0.0.0')
- # # More secure:
+ # LiveConsole.new(:socket, :port => 3030, :host => '0.0.0.0')
+ # # Use a Unix Domain Socket (which is more secure) instead:
# LiveConsole.new(:unix_socket, :path => '/tmp/my_liveconsole.sock',
# :mode => 0600)
#
- # Creates a new LiveConsole. You must next call LiveConsole#run when you
- # want to spawn the thread to accept connections and run the console.
+ # Creates a new LiveConsole. You must next call LiveConsole#start when you
+ # want to spawn the thread to accept connections and start the console.
def initialize(io_method, opts = {})
self.io_method = io_method.to_sym
unless IOMethods::List.include?(self.io_method)
@@ -40,10 +41,10 @@ def initialize(io_method, opts = {})
init_io opts
end
- # LiveConsole#run spawns a thread to listen for, accept, and provide an IRB
- # console to new connections. If a thread is already running, this method
- # simply returns false; otherwise, it returns the new thread.
- def run
+ # LiveConsole#start spawns a thread to listen for, accept, and provide an
+ # IRB console to new connections. If a thread is already running, this
+ # method simply returns false; otherwise, it returns the new thread.
+ def start
return false if thread
self.thread = Thread.new {
loop {

0 comments on commit 344920a

Please sign in to comment.