rolo 1.0.2

data/README.md

@@ -0,0 +1,111 @@
+## NAME
+
+  `rolo.rb` -- Prevents a program from running more than one copy at a time
+
+## SYNOPSIS
+
+<pre>
+  $0 [-v] [--test] [-a address] -p port command [arguments]
+</pre>
+
+## DESCRIPTION
+
+  `rolo.rb` prevents a program from running more than one copy at a time;
+   it is useful with cron to make sure that a job doesn't run before a
+   previous one has finished. `robo.rb` is a ruby version of Timothy
+   program `solo` with more options.
+
+## OPTIONS
+
+  * `-v` (`--verbose`)
+      Print verbose message
+  * `-t` (`--test`)
+      Test of program is running. Don't execute command.
+  * `-a` (`--address`)
+      Address to check / listen on. By default, this address is
+      `127.x.y.1:<port>` where `x.y` is translated from process's user
+      identity number and this allows two different users on the system
+      can use the same port with `rolo.rb`
+  * `-p` (`--port`)
+      Port to check / on which rolo will listen
+
+In `<command>` and `<arguments>`, you can use `%address`, `%port` which
+are replaced by the socket address and port that the problem uses to
+check for status of your command. This is very useful if your command
+closes all file descriptors at the time it runs, but it has some ways
+to listen on `%address:%port`. See EXAMPLE for details.
+
+## HOW IT WORKS
+
+  Before starting your `<command>` (using `exec`), `rolo.rb` will open a
+  socket on a local address (or address specified by option `--address`.)
+  This socket will be closed after your command exits, and as long as
+  your command is running, we have a chance to check its status by
+  checking the status of this socket. If it is still open when `rolo.rb`
+  is invoked, `rolo.rb` exits without invoking a new instance of command.
+
+  However, if your `<command>` closes all file descriptors at the time it
+  is executed, `rolo.rb` will be sucked. (See `EXAMPLE` for details and for
+  a trick when using `rolo.rb` with `ssh`.) If that the cases, you may
+  use the option `--address` and `--port` to specify a socket that your
+  command binds on.
+
+## EXAMPLE
+
+  To create tunnel to a remote server, you can use this ssh command
+
+<pre>
+ssh -fN remote -L localhost:1234:localhost:10000
+</pre>
+
+  This allows you to connect to the local port 1234 on your mahince
+  as same as conneting to address `localhost:10000` on remote server.
+  The process `ssh` will go to background immediately after it authenticates
+  successfully with the remote.
+
+  To keep this tunnel persistent, you can add this to your crontab
+
+<pre>
+rolo.rb -p 4567 \
+  ssh remote -fNL localhost:1234:localhost:10000
+</pre>
+
+  and allows this line to be executed once every 5 minutes. `rolo.rb`
+  will check if your ssh command is still running. If 'yes', it will
+  simply exit; if 'no', `rolo.rb` will start the ssh command.
+
+  However, if you use *OpenSSH 5.6p1* (or later), `ssh` will close all file
+  descriptors from the parent (except for `STDIN`, `STDOUT` and `STDERR`).
+  As the socket opened by `rolo.rb` is closed, `rolo.rb` will always
+  start new instance of the `ssh` tunnel. (Actually I had process `bomb`
+  on my system when I used the original program `solo` to launch my
+  tunnels.)
+
+  Fortunately, `ssh` has option to bind on the local address.
+  Using this option we can trick `rolo.rb` as below
+<pre>
+rolo.rb -p 4567 \
+  ssh remote -fN \
+    -L localhost:1234:localhost:10000 \
+    -L %address:%port:localhost:12345
+</pre>
+
+  The last use of option `-L` will ask `ssh` to open a socket on
+  `%address:%port` (the real values will be provided by `rolo.rb`),
+  and it will be checked by `rolo.rb` in its next run. Please note that
+  we use a random port `12345` to prevent local connections to
+  `%address:%port` from being forwarded to remote.
+
+  Another way is to use option `--address`
+
+<pre>
+rolo.rb -p 1234 -a 127.0.0.1 \
+  ssh remote -fNL localhost:1234:localhost:10000
+</pre>
+
+  And this is another way
+
+<pre>
+rolo.rb -p 1234 -a 127.0.0.1 \
+  ssh remote -fNL %address:%port:localhost:10000
+</pre>

data/bin/rolo

@@ -0,0 +1,144 @@
+#!/usr/bin/env ruby
+#
+# Purpose: Prevents a program from running more than one copy at a time
+# Author : Anh K. Huynh
+# License: GPL2
+# Date   : 2012 July 16th
+# Source : http://github.com/icy/rolo
+# Link   : [1] Tim's solo: http://github.com/timkay/solo/
+#          [2] Fork-exec : http://en.wikipedia.org/wiki/Fork-exec
+#          [3] Unix fork : http://www-h.eng.cam.ac.uk/help/tpl/unix/fork.html
+#          [4] Fork-exec : http://jacktang.github.com/2009/01/04/ruby-fork-exec-socket-hang.html
+#          [5] ^F in Perl: http://perldoc.perl.org/perlvar.html#%24^F
+#          [6] RubyPaint : http://ruby.runpaint.org/io
+#          [7] Secure FD : http://udrepper.livejournal.com/20407.html
+#          [8] OpenSSH   : http://ftp.openbsd.org/pub/OpenBSD/OpenSSH/portable/openssh-5.9p1.tar.gz
+#          [9] closefrom : http://www.unix.com/man-page/All/3c/closefrom/
+#
+# Note [5]:
+#   The maximum system file descriptor, ordinarily 2. System file descrip-
+#   tors are passed to exec()ed processes, while higher file descriptors
+#   are not. Also, during an open(), system file descriptors are preserved
+#   even if the open() fails (ordinary file descriptors are closed before
+#   the open() is attempted). The close-on-exec status of a file descrip-
+#   tor will be decided according to the value of $^F when the correspon-
+#   ding file, pipe, or socket was opened, not the time of the exec().
+#
+# Note [6]:
+#   On a Unix-based system a process created by Kernel.exec, Kernel.fork,
+#   or IO.popen inherits the file descriptors of its parent. Depending on
+#   the application, this may constitute an information leak in that the
+#   child is able to access data that he shouldn’t have access to. If
+#   given a true argument, IO#close_on_exec= ensures that its receiver
+#   is closed before the new process is created; otherwise, it does not.
+#   IO#close_on_exec? returns the status of this flag as either true or
+#   false. On systems that don’t support this feature, these methods
+#   raise NotImplementedError.
+#
+# Note [8]:
+#   In the source code of OpenSSH 5.9p1, ssh.c::268 we can see that all
+#   file descriptors from (STDERR_FILENO + 1) will be closed by the
+#   function (closefrom) (see [9].) This may cause problem!
+#
+#   /*
+#   * Discard other fds that are hanging around. These can cause problem
+#   * with backgrounded ssh processes started by ControlPersist.
+#   */
+#   closefrom(STDERR_FILENO + 1);
+#
+#   On my system (ArchLinux, 3.3.8), (closefrom) is not found. The method
+#   should be used from (openbsd-compact/bsd-closefrom.c).s
+#
+#   This behavior is implemented since OpenSSH 5.6p1.
+#
+
+require 'socket'
+
+class String
+  def die(ret = 1, dev = STDERR, prefix = ":: ")
+    dev.puts("#{prefix}#{self}")
+    exit(ret)
+  end
+
+  def verbose(v = false)
+    STDERR.puts(":: #{self}") if v
+  end
+end
+
+# Based on the original code taken from from [4]
+def close_on_exec(att = true)
+  ObjectSpace.each_object(IO) do |io|
+    begin
+      if io.respond_to?(:close_on_exec?)
+        io.close_on_exec = attr
+      else
+        io.fcntl(Fcntl::F_SETFD, attr ? Fcntl::FD_CLOEXEC : 0)
+      end
+    rescue ::Exception => err
+    end unless [STDIN, STDOUT, STDERR].include?(io) or io.closed?
+  end
+end
+
+OPTIONS = {:verbose => false, :port => 0}
+
+"Syntax: rolo [--verbose] [--test] [--address <address>] --port <port_number> <command> [<arguments>]".die if ARGV.empty?
+
+while true
+  f = ARGV.first
+  if %w{-p --port}.include?(f)
+    ARGV.shift
+    OPTIONS[:port] = ARGV.shift.to_s.to_i
+    "Port must be a positive number".die if OPTIONS[:port] == 0
+  elsif %w{-v --verbose}.include?(f)
+    OPTIONS[:verbose] = true
+    ARGV.shift
+  elsif %w{-a --address}.include?(f)
+    ARGV.shift
+    OPTIONS[:address] = ARGV.shift.to_s.strip
+    "Invalid address '#{OPTIONS[:address]}' was provided. Should be in format 'x.y.z.t'".die \
+      unless OPTIONS[:address].match(/^[0-9]+\.[0-9]+\.[0-9]+\.[0-9]+$/)
+  elsif %w{-m --message}.include?(f)
+    ARGV.shift
+    OPTIONS[:message] = ARGV.shift
+  elsif %w{-t --test}.include?(f)
+    OPTIONS[:test] = true
+    ARGV.shift
+  elsif %w{--}.include?(f)
+    ARGV.shift
+    break
+  else
+    break
+  end
+end
+
+"Port must be a positive number".die if OPTIONS[:port] == 0
+
+cmd = ARGV.shift.to_s
+"You must provide a command".die if cmd.empty?
+cmd = "#{cmd} #{ARGV.join(' ')}" unless ARGV.empty?
+
+address = OPTIONS[:address] || [127, Process.uid, 1].pack("CnC").unpack("C4").join(".")
+
+cmd = cmd.gsub("%port", OPTIONS[:port].to_s).gsub("%address", address)
+
+("Will bind on %s:%d, command = '%s'" \
+  % [address, OPTIONS[:port], cmd]).verbose(OPTIONS[:verbose])
+
+# Taken from example in the source code documetation
+# Link: http://ruby-doc.org/stdlib-1.8.7/
+#         libdoc/socket/rdoc/Socket.html#method-i-bind
+begin
+  include Socket::Constants
+  socket = Socket.new(AF_INET, SOCK_STREAM, 0)
+  socket.bind(Socket.pack_sockaddr_in(OPTIONS[:port], address))
+  socket.close if OPTIONS[:address]
+rescue Errno::EADDRINUSE
+  (OPTIONS[:message] || ":: Address is in use. Is your application running?").die(0, STDOUT, "")
+rescue => e
+  e.to_s.die(1)
+end
+
+unless OPTIONS[:test]
+  close_on_exec(false)
+  exec cmd
+end

metadata

@@ -0,0 +1,47 @@
+--- !ruby/object:Gem::Specification
+name: rolo
+version: !ruby/object:Gem::Version
+  version: 1.0.2
+  prerelease: 
+platform: ruby
+authors:
+- Anh K. Huynh
+autorequire: 
+bindir: bin
+cert_chain: []
+date: 2012-07-20 00:00:00.000000000 Z
+dependencies: []
+description: Prevents a program from running more than one copy at a time
+email: kyanh@viettug.org
+executables:
+- rolo
+extensions: []
+extra_rdoc_files: []
+files:
+- README.md
+- bin/rolo
+homepage: https://github.com/icy/rolo
+licenses: []
+post_install_message: 
+rdoc_options: []
+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.16
+signing_key: 
+specification_version: 3
+summary: ! '`rolo` prevents a program from running more than one copy at a time'
+test_files: []