net-server 1.0.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA1:
+  metadata.gz: befb3239d96b9cb8652bd568665eb15fe7b17d06
+  data.tar.gz: 9c7ae1db07ae3a5ce071ec49c346b02bb8d659ff
+SHA512:
+  metadata.gz: a331a3bf1acb62e4d1eb820a642e1195376923ff724cae5abdef51f057737780573585f1f90c163ae1656f40920a488cda7c92c170aea04b1d667d96898881f4
+  data.tar.gz: 22c82197fa151e9aaa114b44f199d70de7c59e64ed3a45b6d8103999064524f594ba6f0ba7407e12d5bc4fe56e87002a870ddf08066420d02c3c4c57d782ab62

data/CHANGELOG.md

@@ -0,0 +1,2 @@
+# v1.0
+This is the initial load of the gem. This gem was taken from an earlier work of mine, so as far as I know, it is bug-free (but never count on code being bug free). If you find a problem, report it to me at mjwelchphd@gmail.com, or FORK the library, fix the bug, then add a Pull Request.

data/README.md

@@ -0,0 +1,158 @@
+# Net::Server
+The Net::Server Ruby gem is a server for web apps. It's purpose is to establish one or more listeners, and create a process to handle each incoming request. 
+
+#### It has the following features:
+1. It can listen on any number of ports simultaneously.
+2. It starts a separate receiver process to handle each connection.
+3. The server may run as root, but the processes will lose their root privileges soon after creation. This is a security feature.
+4. The receiver processes can switch on full encryption (STARTTLS in a mail server, for example).
+5. A log file will be used, if it exists. You create the log using the 'logger' gem.
+7. Runs until terminated by a `KILL -INT <pid>` or `^C`.
+9. Two example programs are included.
+
+### TODO
+* RSPEC tests.
+
+# Gem Dependancies
+This gem requires the following:
+```ruby
+require 'openssl'
+require 'socket'
+```
+Both of these packages are found in the Ruby Standard Library (stdib 2.2.2 at the time of this writing). They are required in the gem itself, so you don't have to require them.
+
+# Creating a Self-Signed Certificate
+Use OpenSSL to create a self-signed certificate for testing as follows:
+```bash
+$ openssl req -x509 -newkey rsa:2048 -keyout example.key -out example.crt -days 9000 -nodes
+$ chmod 400 example.key
+$ chmod 444 example.crt
+```
+Put the two files anywhere you want, and specify their path in the start call (see the last line of the example programs). If you don't specify these two files, they will default to the ones that come with the gem, but since anyone can download the gem and look at the files, they are not secure.
+
+# How to Get Net::Server Gem
+
+To install the gem, simply use the *gem* application:
+```bash
+$ sudo gem install net-server
+```
+Alternately, you can clone the project on GitHub at:
+```bash
+https://github.com/mjwelchphd/net-server
+```
+and build it yourself.
+
+The example programs are only found in the source on GitHub at github.com/mjwelchphd/net-server.
+
+If you're using Builder, follow your normal routine for adding gems.
+
+# How to Build a Basic Server
+
+The basic server looks like this:
+```ruby
+require 'net/server'
+
+class Receiver
+
+  def receive(local_port, local_hostname, remote_port, remote_hostname, remote_ip)
+    <send and receive data>
+  end
+
+end
+
+LOG = Logger::new(<log-file-path>, <log-file-name>)
+
+Net::Server.new(<options>).start
+```
+There are two test applications included in the gem in the examples folder. Test1 just echos a telnet connection. Test2 implements a simple email receiver you can test with swaks.
+
+## Options
+  
+  Option | Default | Description
+  --- | --- | ---
+  :server_name | "example.com" | This name is only used in error messages.
+  :listening_ports | ["25","486","587"] | An array of one or more ports to listen on.
+  :private_key | Internal key | The key for encrypting/decrypting the data when in TLS mode.
+  :certificate | Internal self-signed certificate | The certificate for encrypting/decrypting the data when in TLS mode. This may be your own self-signed certificate, or one you purchase from a Certificate Authority, or you can become a Certificate Authority and sign your own.
+  :user_name | nil | This name is the user name to which each process will be switched after it is created. If it is nil, the ownership of the process will not be changed after creation. If you are using a port less than 1024, you must start the server as root, and the user name and group name of the process _must be_ specified.
+  :group_name | nil | This name is the group name to which each process will be switched after it is created.
+  :working_directory | the current path | The location of the program running the server.
+  :pid_file | "pid" | The PID of the server will be stored in this file.
+  :daemon | false | If this option is true, the server will be started as a daemon.
+
+## Logging
+
+The log file must be created by the 'logger' gem, and must be named LOG.
+
+## Terminating the Server
+
+### HUP and INT (^C) traps
+
+A `kill -INT <pid>` or `<ctrl-C>` will terminate the server.
+```bash
+$ test1.rb
+^C
+test1 terminated by admin ^C
+$
+```
+or
+```bash
+sudo kill -INT `cat /run/net-server/net-server.pid`
+```
+
+A `kill -HUP <pid>` will activate a restart method, if you have one defined in your code. For example, if you put this in your code:
+```ruby
+class Server
+  def restart
+  	puts "I just got a HUP request."
+  end
+end
+```
+then at another terminal enter:
+```ruby
+$ ps ax | grep test1
+  823 pts/0    Sl+    0:00 test1.rb
+  829 pts/1    S+     0:00 grep --color=auto test1
+$ kill -hup 823
+```
+or
+```bash
+kill -HUP `cat pid`
+```
+it will result in:
+```bash
+net-server received a HUP request
+I just got a HUP request.
+```
+at the terminal where `test1.rb` is running, with no other action. The first message comes from `net-server` itself, and the second comes from the `def restart` you defined.
+
+#### Example
+
+If you define your options in a class variable Hash object, say @options, if the values change, the new values take effect immediately, except for :daemon which requires a manual restart. For instance,
+
+```ruby
+@options = {
+  :server_name=>"www.example.com",
+  :private_key=>"server.key",
+  :certificate=>"server.crt",
+  :listening_ports=>['2000','2001']
+  :user_name=>"myusername",
+  :group_name=>"mygroupname",
+  :daemon = true
+}
+Net::Server::new(@options).start
+```
+starts the server, then
+```ruby
+class Server
+  def restart
+    @options = {
+      :user_name=>"yourusername",
+      :group_name=>"yourgroupname"}
+  end
+end
+```
+will change the user name and group name for all new processes when the HUP is received.
+
+
+FIN

data/lib/net/server.crt

@@ -0,0 +1,17 @@
+-----BEGIN CERTIFICATE-----
+MIICqDCCAZACCQDi3G+g2cQKIjANBgkqhkiG9w0BAQsFADAWMRQwEgYDVQQDDAtl
+eGFtcGxlLmNvbTAeFw0xNjA5MTIwMzIxMTFaFw00NDAxMjgwMzIxMTFaMBYxFDAS
+BgNVBAMMC2V4YW1wbGUuY29tMIIBIjANBgkqhkiG9w0BAQEFAAOCAQ8AMIIBCgKC
+AQEAyjrhith3b09fjtDIFm+PO4MvyjN75Q5FyNJrB7Nwbtrs0U+cM+LqUa7IogV5
+LNXNOq1NxX3b8AmrZ3PRJ0OU+SWcMQcQLWb027R2agHHH4M7haYtpZh33u7+cLo9
+sCwm7d2S9ShgFPNVeIMuEjbwXKj1beHTYbljeEFULgxsqrvUJWm1A+WgPFc/9QyX
+os7gv9VG0//qlCAY91QEx7LGN+XEhzSzfOHnAwYeB8qYKbf7CRK4hua2zoCZQB0d
+o4IHm+aS6HSSsnTQ/JHWegjy/yyJAenseXRdmz1O4yj+nw5yFocz7TbqgQm5jqgV
+acEmX2b6tiuOlwc9Hm9x6Z0BLQIDAQABMA0GCSqGSIb3DQEBCwUAA4IBAQCyCw/H
+XPxV1P6WVZFgQ65/IKZoJY6JSZ88ILw0jzN/B+/ItfBk250n1VoDv9sNXeDg6Sym
+cNlJlS5nwAzVE+drELu6xMbAOX0+y4KHhhYTrl+8CnXWXVVGsUQhHu8GljfMbM+s
+VUNrhWO8XRrQ4u4wqnh1kR1pe2xUhuV3dkespWI4LRjNnsEmPw3Rg5BkY8VQRKSR
+Srif5BlisnwE1WDefaIiE7Ydgs93o1FxZchvBnlHrtxnCG+bXIlO29fRdX8rUpH/
+zgONQ97oJHZ4N29AEYO8dxnEt8e9eioeQU+xeU8HRw36F+JajiqhCOwgpz7Vv4rn
+HmueeHzDxJaGD+xv
+-----END CERTIFICATE-----

data/lib/net/server.key

@@ -0,0 +1,27 @@
+-----BEGIN RSA PRIVATE KEY-----
+MIIEpAIBAAKCAQEAyjrhith3b09fjtDIFm+PO4MvyjN75Q5FyNJrB7Nwbtrs0U+c
+M+LqUa7IogV5LNXNOq1NxX3b8AmrZ3PRJ0OU+SWcMQcQLWb027R2agHHH4M7haYt
+pZh33u7+cLo9sCwm7d2S9ShgFPNVeIMuEjbwXKj1beHTYbljeEFULgxsqrvUJWm1
+A+WgPFc/9QyXos7gv9VG0//qlCAY91QEx7LGN+XEhzSzfOHnAwYeB8qYKbf7CRK4
+hua2zoCZQB0do4IHm+aS6HSSsnTQ/JHWegjy/yyJAenseXRdmz1O4yj+nw5yFocz
+7TbqgQm5jqgVacEmX2b6tiuOlwc9Hm9x6Z0BLQIDAQABAoIBAEfEoao+rBQqnQT3
+/ypHKRO7uMgPgVaGvClK04UGH06YDxcxI4QecX3Pg5BMVPaeYZkDS+hchCMpq1Sp
+e35ts36/5DBaC1mxghA+eQ+h1eLPFd6WXPi5pUDOnCmxTpco9B/SVIcAbyjAOoLs
+Ovtn1+FqbL80N2ok+rIArTkyW5YzNNT84P5nMLGL5PvA40F/dGhkIUutX73F8jvU
+th3OLyf2MTYKfq7J79z3CGrClZmdcD70h5oKcVH0xFISODqwW9+NUuCaZke0LLPm
+TLQlFdKxfu5rVoBW6DGsK+7q4LSG41MkXTyTi2yIW70ls++KakJi4QcYetX/XPTa
+Xd1YkhkCgYEA5Gqj7wLIpvdtyIbM08xF7eUhuXxx42OHAvirFu/l9WipTRBvoLg2
+CCOWAr/1UyWDeIJAEOjsplKEN0NH1Yx9+jgXbzEU1rVtW8+Oyd64/FJqjICZPatp
+DBTxyPy1849PcyhlFHMiPiaP8+bcuy8HVeLDd27gujjJDtNYL9mAxBcCgYEA4qay
+86WqUCZqjOXrEPh4/VWqT0lvvkoBaOx3ScoapXZlKFJAf1lNd7pEvvTZ/6X5XCbr
+8VA+wUB1kQAKjVBPxideIyUOKboJJfgJDWqTaiPtOdCbO9+pcEsu/1Ep+64prU1e
+dX85McHKGRJZEPQOqIXT+M+m6iJ5Dr63KMtKO1sCgYEA5EJ9WFhb1B7nIsEy52T3
+bOjRbt8hoK7ROPLvZpiOIVRZ+501MFNmC3QkcNMLge+3FjJze3KJKxzC68bcfldL
+fUWYhZFy1a2wf1NHygw8qEpkF8xbVvl4nI5BoSyJV8AbEWWIvYrg6WL38DEA3D3/
+AqD93Nh80xv0MFCbjBW7TDkCgYA5MOks89ui996hCQ8krB4Thr8/3H723EO4zxpW
+o0nQAK0L3J1rxQP4NydLrAsqKB5g821L6fy71OEVopYHDIHktWBaq+oD+259hzX5
+ja/+82vTz+Cr3gcqT75fLILUgCECGui/60dqV8UASJHy5jKgsYxIV1V99Q7o+pTL
+FWj4ywKBgQCtJ/xOSowLSdEYGRq//iNKaBSAutaV26J5WVxxev3wUehZpvRGtqI5
+CiddA8vlR0EiA/SINQ0MZtk9kwvWYVq/jkWGttK6gwU26ZDUR7xUOMs17m3ttUn7
+mjkuyOITFCRxf0x0LcoFQWHlc5lC6Y/ZKF3dK6jPD74B5/UUeQ8sCA==
+-----END RSA PRIVATE KEY-----

data/lib/net/server.rb

@@ -0,0 +1,237 @@
+# = net/server.rb
+#
+# Copyright (c) 2016 Michael J. Welch, Ph.D.
+#
+# Written and maintained by Michael J. Welch, Ph.D. <mjwelchphd@gmail.com>
+#
+# This work is not derived from any other work. It is original software.
+#
+# Documented by Michael J. Welch, Ph.D. <mjwelchphd@gmail.com>
+#
+# This program is free software. You can re-distribute and/or
+# modify this program under the same terms as Ruby itself.
+#
+# See the README.md for documentation.
+#
+
+require 'openssl'
+require 'socket'
+
+module Net
+
+  # :stopdoc:
+  class ServerTerminate < Exception; end
+  class ServerQuit < Exception; end
+  # :startdoc:
+
+  # == An Internet server
+  class Server
+
+private
+
+    def initialize(options={})
+      path = __FILE__.chomp('server.rb')
+      @option_list = [[:server_name, "example.com"], [:listening_ports, ["25","486","587"]], \
+        [:private_key, "#{path}server.key"], [:certificate, "#{path}server.crt"], \
+        [:user_name, nil], [:group_name, nil], [:working_directory, File::realpath('.')], \
+        [:pid_file, "pid"], [:daemon, false]]
+      @options = {}
+      @option_list.each do |key,value|
+        @options[key] = if options.has_key?(key) then options[key] else value end
+      end
+    end # initialize
+
+    include Socket::Constants
+
+    #
+    # This is the code executed after the process has been
+    # forked and root privileges have been dropped.
+    #
+    def process_call(connection, local_port, remote_port, remote_ip, remote_hostname, remote_service)
+      begin
+        Signal.trap("INT") { } # ignore ^C in the child process
+        LOG.info("%06d"%Process::pid) {"Connection accepted on port #{local_port} from port #{remote_port} at #{remote_ip} (#{remote_hostname})"} if LOG
+
+        # a new object is created here to provide separation between server and receiver
+        # this call receives the email and does basic validation
+        Receiver::new(connection).receive(local_port, Socket::gethostname, remote_port, remote_hostname, remote_ip)
+      rescue ServerQuit
+        # nothing to do here
+      end
+    end # process_call
+
+    #
+    # This method drops the process's root privileges for security reasons.
+    #
+    def drop_root_privileges(user_name, group_name, working_directory)
+      # drop root privileges
+      if Process::Sys.getuid==0
+        user = Etc::getpwnam(user_name)
+        group = Etc::getgrnam(group_name)
+        Dir.chdir(user.dir)
+        Dir.chdir(working_directory) if not working_directory.nil?
+        Process::GID.change_privilege(group.gid)
+        Process::UID.change_privilege(user.uid)
+      end
+    end # drop_root_privileges
+
+    #
+    # both the AF_INET and AF_INET6 families use this DRY method
+    # to bind to the socket.
+    #
+    def bind_socket(family,port,ip)
+      socket = Socket.new(family, SOCK_STREAM, 0)
+      sockaddr = Socket.sockaddr_in(port.to_i,ip)
+      socket.setsockopt(:SOCKET, :REUSEADDR, true)
+      socket.bind(sockaddr)
+      socket.listen(0)
+      return socket
+    end # bind_socket
+
+    #
+    # The listening thread is established in this method depending on the ListenPort
+    # argument passed to it -- it can be '<ipv6>/<port>', '<ipv4>:<port>', or just '<port>'.
+    #
+    def listening_thread(local_port)
+      LOG.info("%06d"%Process::pid) {"listening on port #{local_port}..."} if LOG
+
+      # establish an SSL context
+      $ctx = OpenSSL::SSL::SSLContext.new
+      $ctx.key = $prv
+      $ctx.cert = $crt
+      
+      # check the parameter to see if it's valid
+      m = /^(([0-9a-fA-F]{0,4}:{0,1}){1,8})\/([0-9]{1,5})|(([0-9]{1,3}\.{0,1}){4}):([0-9]{1,5})|([0-9]{1,5})$/.match(local_port)
+      #<MatchData "2001:4800:7817:104:be76:4eff:fe05:3b18/2000" 1:"2001:4800:7817:104:be76:4eff:fe05:3b18" 2:"3b18" 3:"2000" 4:nil 5:nil 6:nil 7:nil>
+      #<MatchData "23.253.107.107:2000" 1:nil 2:nil 3:nil 4:"23.253.107.107" 5:"107" 6:"2000" 7:nil>
+      #<MatchData "2000" 1:nil 2:nil 3:nil 4:nil 5:nil 6:nil 7:"2000">
+      case
+        when !m[1].nil? # it's AF_INET6
+          socket = bind_socket(AF_INET6,m[3],m[1])
+        when !m[4].nil? # it's AF_INET
+          socket = bind_socket(AF_INET,m[6],m[4])
+        when !m[7].nil?
+          socket = bind_socket(AF_INET6,m[7],"0:0:0:0:0:0:0:0")
+        else
+          raise ArgumentError.new(local_port)
+      end # case
+      ssl_server = OpenSSL::SSL::SSLServer.new(socket, $ctx);
+
+      # main listening loop starts in non-encrypted mode
+      ssl_server.start_immediately = false
+      loop do
+        # we can't use threads because if we drop root privileges on any thread,
+        # they will be dropped for all threads in the process--so we have to fork
+        # a process here in order that the reception be able to drop root privileges
+        # and run at a user level--this is a security precaution--the other reason
+        # to use processes is that they can be run on multiple processors
+        connection = ssl_server.accept
+        Process::fork do
+          # now we're in the child process
+          begin
+            drop_root_privileges(@options[:user_name],@options[:group_name],@options[:working_directory]) if !@options[:user_name].nil?
+            remote_hostname, remote_service = connection.io.remote_address.getnameinfo
+            remote_ip, remote_port = connection.io.remote_address.ip_unpack
+            process_call(connection, local_port, remote_port.to_s, remote_ip, remote_hostname, remote_service)
+          ensure
+            # here we close the child's copy of the connection --
+            # since the parent already closed it's copy, this
+            # one will send a FIN to the client, so the client
+            # can terminate gracefully
+            connection.close
+            LOG.info("%06d"%Process::pid) {"Connection closed on port #{local_port} by #{@options[:server_name]}"} if LOG
+            # and finally, close the child's link to the log
+            LOG.close if LOG
+          end
+          # the child process ends here
+        end # fork
+        # now we're in the parent process
+        # here we close the parent's copy of the connection --
+        # the child (created by the Process::fork above) has another copy --
+        # if this one is not closed, when the child closes it's copy,
+        # the child's copy won't send a FIN to the client -- the FIN
+        # is only sent when the last process holding a copy to the
+        # socket closes it's copy
+        connection.close
+      end # loop
+    end # listening_thread
+
+public
+
+    #
+    # This is the main setup and loop.
+    #
+    def start
+      # generate the first log messages
+      LOG.info("%06d"%Process::pid) {"Starting RubyMTA at #{Time.now.strftime("%Y-%m-%d %H:%M:%S %Z")}, pid=#{Process::pid}"} if LOG
+      LOG.info("%06d"%Process::pid) {"Options specified: #{ARGV.join(", ")}"} if LOG && ARGV.size>0
+
+      # get the certificates, if any; they're needed for STARTTLS
+      # we do this before daemonizing because the working folder might change
+      $prv = if @options[:private_key] then OpenSSL::PKey::RSA.new File.read(@options[:private_key]) else nil end
+      $crt = if @options[:certificate] then OpenSSL::X509::Certificate.new File.read(@options[:certificate]) else nil end
+
+      # daemonize it if the option was set--it doesn't have to be root to daemonize it
+      Process::daemon if @options[:daemon]
+
+      # get the process ID and the user id AFTER demonizing, if that was requested
+      pid = Process::pid
+      uid = Process::Sys.getuid
+      gid = Process::Sys.getgid
+      
+      LOG.info("%06d"%Process::pid) {"Daemonized at #{Time.now.strftime("%Y-%m-%d %H:%M:%S %Z")}, pid=#{pid}, uid=#{uid}, gid=#{gid}"} if LOG && @options[:daemon]
+
+      # store the pid of the server session
+      begin
+        puts "RubyMTA running as PID=>#{pid}, UID=>#{uid}, GID=>#{gid}"
+        File.open(@options[:pid_file],"w") { |f| f.write(pid.to_s) }
+      rescue Errno::EACCES => e
+        LOG.warn("%06d"%Process::pid) {"The pid couldn't be written. To save the pid, create a directory for '#{@options[:pid_file]}' with r/w permissions for this user."} if LOG
+        LOG.warn("%06d"%Process::pid) {"Proceeding without writing the pid."} if LOG
+      end
+
+      # if ssltransportagent was started as root, make sure UserName and
+      # GroupName have values because we have to drop root privileges
+      # after we fork a process for the receiver
+      if uid==0 # it's root
+        if @options[:user_name].nil? || @options[:group_name].nil?
+          LOG.error("%06d"%Process::pid) {"ssltransportagent can't be started as root unless UserName and GroupName are set."} if LOG
+          exit(1)
+        end
+      end
+
+      # this is the main loop which runs until admin enters ^C
+      Signal.trap("INT") { raise ServerTerminate.new }
+      Signal.trap("HUP") { restart if defined?(restart) }
+      Signal.trap("CHLD") do
+        begin
+        Process.wait(-1, Process::WNOHANG)
+        rescue Errno::ECHILD => e
+          # ignore the error
+        end
+      end # trap-chld
+      threads = []
+      # start the server on multiple ports (the usual case)
+      begin
+        @options[:listening_ports].each do |port|
+          threads << Thread.start(port) do |port|
+            listening_thread(port)
+          end
+        end
+        # the joins are done ONLY after all threads are started
+        threads.each { |thread| thread.join }
+      rescue ServerTerminate
+        LOG.info("%06d"%Process::pid) {"#{@options[:server_name]} terminated by admin ^C"} if LOG
+      end
+
+      # attempt to remove the pid file
+      begin
+        File.delete(@options[:pid_file])
+      rescue Errno::ENOENT => e
+        LOG.warn("%06d"%Process::pid) {"No such file: #{e.inspect}"} if LOG
+      rescue Errno::EACCES, Errno::EPERM
+        LOG.warn("%06d"%Process::pid) {"Permission denied: #{e.inspect}"} if LOG
+      end
+    end # start
+  end
+end

data/lib/net/version.rb

@@ -0,0 +1,4 @@
+module Net
+  BUILD_VERSION = "1.0.0"
+  BUILD_DATE = "2015-09-13"
+end

metadata

@@ -0,0 +1,50 @@
+--- !ruby/object:Gem::Specification
+name: net-server
+version: !ruby/object:Gem::Version
+  version: 1.0.0
+platform: ruby
+authors:
+- Michael J. Welch, Ph.D.
+autorequire: 
+bindir: bin
+cert_chain: []
+date: 2015-09-13 00:00:00.000000000 Z
+dependencies: []
+description: Ruby Net server.
+email:
+- mjwelchphd@gmail.com
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- CHANGELOG.md
+- README.md
+- lib/net/server.crt
+- lib/net/server.key
+- lib/net/server.rb
+- lib/net/version.rb
+homepage: https://github.com/mjwelchphd/net-server
+licenses:
+- MIT
+metadata: {}
+post_install_message: 
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubyforge_project: 
+rubygems_version: 2.4.6
+signing_key: 
+specification_version: 4
+summary: Ruby Net server.
+test_files: []