investtools-ftpd 1.0.1

data/doc/references.md

@@ -0,0 +1,66 @@
+# REFERENCES
+
+## RFCs
+
+_This list of references comes from the README of the em-ftpd gem,
+which is licensed under the same MIT license as this gem, and is
+Copyright (c) 2008 James Healy_
+
+There are a range of RFCs that together specify the FTP protocol. In
+chronological order, the more useful ones are:
+
+* [RFC-854](http://tools.ietf.org/rfc/rfc854.txt) - Telnet Protocol
+  Specification
+
+* [RFC-959](http://tools.ietf.org/rfc/rfc959.txt) - File Transfer
+  Protocol
+
+* [RFC-1123](http://tools.ietf.org/rfc/rfc1123.txt) - Requirements for
+  Internet Hosts
+
+* [RFC-1143](http://tools.ietf.org/rfc/rfc1143.txt) - The Q Method of
+  Implementing TELNET Option Negotation
+
+* [RFC-2228](http://tools.ietf.org/rfc/rfc2228.txt) - FTP Security
+  Extensions
+
+* [RFC-2389](http://tools.ietf.org/rfc/rfc2389.txt) - Feature
+  negotiation mechanism for the File Transfer Protocol
+
+* [RFC-2428](http://tools.ietf.org/rfc/rfc2428.txt) - FTP Extensions
+  for IPv6 and NATs
+
+* [RFC-2577](http://tools.ietf.org/rfc/rfc2577.txt) - FTP Security
+  Considerations
+
+* [RFC-2640](http://tools.ietf.org/rfc/rfc2640.txt) -
+  Internationalization of the File Transfer Protocol
+
+* [RFC-3659](http://tools.ietf.org/rfc/rfc3659.txt) - Extensions to
+  FTP
+
+* [RFC-4217](http://tools.ietf.org/rfc/rfc4217.txt) -
+  Securing FTP with TLS
+
+For an english summary that's somewhat more legible than the RFCs, and
+provides some commentary on what features are actually useful or
+relevant 24 years after RFC959 was published:
+
+* <http://cr.yp.to/ftp.html>
+
+For a history lesson, check out Appendix III of RCF959. It lists the
+preceding (obsolete) RFC documents that relate to file transfers,
+including the ye old RFC114 from 1971, "A File Transfer Protocol"
+
+There is a [public test server](http://secureftp-test.com) which is
+very handy for checking out clients, and seeing how at least one
+server behaves.
+
+## How to reliably close a socket (and not lose data)
+
+[Why is my TCP not reliable](http://ia600609.us.archive.org/22/items/TheUltimateSo_lingerPageOrWhyIsMyTcpNotReliable/the-ultimate-so_linger-page-or-why-is-my-tcp-not-reliable.html) by Bert Hubert
+
+## LIST output format
+
+* [GNU docs for ls](http://www.gnu.org/software/coreutils/manual/html_node/What-information-is-listed.html#What-information-is-listed)
+* [Easily Parsed LIST format (EPLF)](http://cr.yp.to/ftp/list/eplf.html)

data/doc/rfc-compliance.md

@@ -0,0 +1,292 @@
+# RFC compliance
+
+This page documents FTPDs compliance (or not) with the RFCs that
+define the FTP protocol.
+
+This document is modeled after [this one from the pyftpdlib
+wiki](http://code.google.com/p/pyftpdlib/wiki/RFCsCompliance).
+pyftpdlib is what every FTP library wants to be when it grows up.
+
+## RFC-959 - File Transfer Protocol
+
+* Issued: October 1985
+* Status: STANDARD
+* Obsoletes: [RFC-765](http://tools.ietf.org/rfc/rfc765.txt)
+* Updated by: 
+ [RFC-1123](http://tools.ietf.org/rfc/rfc1123.txt)
+ [RFC-2228](http://tools.ietf.org/rfc/rfc2228.txt)
+ [RFC-2640](http://tools.ietf.org/rfc/rfc2640.txt)
+ [RFC-2773](http://tools.ietf.org/rfc/rfc2773.txt)
+* [link](http://tools.ietf.org/rfc/rfc959.txt)
+
+Commands supported:
+
+    ABOR    No      ---     Abort transfer
+    ACCT    Yes    0.4.0    Specify user's account
+    ALLO    Yes    0.2.0    Allocate storage space
+                            Treated as a NOOP
+    APPE    Yes    0.4.0    Append to file
+    CDUP    Yes    0.1.0    Change to parent directory    
+    CWD     Yes    0.1.0    Change working directory    
+    DELE    Yes    0.1.0    Delete file    
+    HELP    Yes    0.2.2    Help
+    LIST    Yes    0.1.0    List directory    
+    MKD     Yes    0.2.1    Make directory    
+    MODE    Yes    0.1.0    Set transfer mode
+                            "Stream" mode supported; "Block" and
+                            "Compressed" are not
+    NLST    Yes    0.1.0    Name list    
+    NOOP    Yes    0.1.0    No Operation    
+    PASS    Yes    0.1.0    Set user password    
+    PASV    Yes    0.1.0    Set passive mode    
+    PORT    Yes    0.1.0    Set active mode    
+    PWD     Yes    0.1.0    Print working directory    
+    QUIT    Yes    0.1.0    Quit session    
+    REIN    No      ---     Reinitialize session    
+    REST    No      ---     Restart transfer    
+    RETR    Yes    0.1.0    Retrieve file    
+    RMD     Yes    0.2.1    Remove directory    
+    RNFR    Yes    0.2.1    Rename file (from)    
+    RNTO    Yes    0.2.1    Rename file (to)    
+    SITE    No      ---     Site specific commands
+    SMNT    No      ---     Structure Mount    
+    STAT    Yes    0.5.0    Server status    
+    STOR    Yes    0.1.0    Store file    
+    STOU    Yes    0.2.2    Store with unique name    
+    STRU    Yes    0.1.0    Set file structure
+                            Supports "File" structure only. "Record" and
+                            "Page" are not supported
+    SYST    Yes    0.2.0    Get system type
+                            Always returns "UNIX Type: L8"
+    TYPE    Yes    0.1.0    Set representation type
+                            Supports ascii non-print and binary-non-print
+                            only
+    USER    Yes    0.1.0    Set user    
+
+## RFC-1123 - Requirements for Internet Hosts
+
+Extends and clarifies some aspects of RFC-959. Introduces new response
+codes 554 and 555.
+
+* Issued: October 1989
+* Status: STANDARD
+* [link](http://tools.ietf.org/rfc/rfc1123.txt)
+
+The following compliance table is lifted out of the RFC and annotated
+with "C" where FTPD complies, or "E" where compliance is not required.
+
+<pre>
+                                           |               | | | |S| |
+                                           |               | | | |H| |F
+                                           |               | | | |O|M|o
+                                           |               | |S| |U|U|o
+                                           |               | |H| |L|S|t
+                                           |               |M|O| |D|T|n
+                                           |               |U|U|M| | |o
+                                           |               |S|L|A|N|N|t
+                                           |               |T|D|Y|O|O|t
+FEATURE                                    |SECTION        | | | |T|T|e
+-------------------------------------------|---------------|-|-|-|-|-|--
+Implement TYPE T if same as TYPE N         |4.1.2.2        | |x| | | |  C
+File/Record transform invertible if poss.  |4.1.2.4        | |x| | | |  C
+Server-FTP implement PASV                  |4.1.2.6        |x| | | | |  C
+  PASV is per-transfer                     |4.1.2.6        |x| | | | |  C
+NLST reply usable in RETR cmds             |4.1.2.7        |x| | | | |  C
+Implied type for LIST and NLST             |4.1.2.7        | |x| | | |  C
+SITE cmd for non-standard features         |4.1.2.8        | |x| | | |  C
+STOU cmd return pathname as specified      |4.1.2.9        |x| | | | |  C
+Use TCP READ boundaries on control conn.   |4.1.2.10       | | | | |x|  C
+Server-FTP send only correct reply format  |4.1.2.11       |x| | | | |  C
+Server-FTP use defined reply code if poss. |4.1.2.11       | |x| | | |  C
+  New reply code following Section 4.2     |4.1.2.11       | | |x| | |  E
+Default data port same IP addr as ctl conn |4.1.2.12       |x| | | | |  C
+Server-FTP handle Telnet options           |4.1.2.12       |x| | | | |  C
+Handle "Experimental" directory cmds       |4.1.3.1        | |x| | | |  C
+Idle timeout in server-FTP                 |4.1.3.2        | |x| | | |  C
+    Configurable idle timeout              |4.1.3.2        | |x| | | |  C
+Receiver checkpoint data at Restart Marker |4.1.3.4        | |x| | | |  E
+Sender assume 110 replies are synchronous  |4.1.3.4        | | | | |x|  E
+                                           |               | | | | | |  -
+Support TYPE:                              |               | | | | | |  -
+  ASCII - Non-Print (AN)                   |4.1.2.13       |x| | | | |  C
+  ASCII - Telnet (AT) -- if same as AN     |4.1.2.2        | |x| | | |  C
+  ASCII - Carriage Control (AC)            |959 3.1.1.5.2  | | |x| | |  E
+  EBCDIC - (any form)                      |959 3.1.1.2    | | |x| | |  E
+  IMAGE                                    |4.1.2.1        |x| | | | |  C
+  LOCAL 8                                  |4.1.2.1        |x| | | | |  C
+  LOCAL m                                  |4.1.2.1        | | |x| | |2 E
+                                           |               | | | | | |  -
+Support MODE:                              |               | | | | | |  -
+  Stream                                   |4.1.2.13       |x| | | | |  C
+  Block                                    |959 3.4.2      | | |x| | |  E
+                                           |               | | | | | |  -
+Support STRUCTURE:                         |               | | | | | |  -
+  File                                     |4.1.2.13       |x| | | | |  C
+  Record                                   |4.1.2.13       |x| | | | |3 E
+  Page                                     |4.1.2.3        | | | |x| |  E
+                                           |               | | | | | |  -
+Support commands:                          |               | | | | | |  -
+  USER                                     |4.1.2.13       |x| | | | |  C
+  PASS                                     |4.1.2.13       |x| | | | |  C
+  ACCT                                     |4.1.2.13       |x| | | | |  C
+  CWD                                      |4.1.2.13       |x| | | | |  C
+  CDUP                                     |4.1.2.13       |x| | | | |  C
+  SMNT                                     |959 5.3.1      | | |x| | |  E
+  REIN                                     |959 5.3.1      | | |x| | |  E
+  QUIT                                     |4.1.2.13       |x| | | | |  C
+                                           |               | | | | | |  -
+  PORT                                     |4.1.2.13       |x| | | | |  C
+  PASV                                     |4.1.2.6        |x| | | | |  C
+  TYPE                                     |4.1.2.13       |x| | | | |1 C
+  STRU                                     |4.1.2.13       |x| | | | |1 C
+  MODE                                     |4.1.2.13       |x| | | | |1 C
+                                           |               | | | | | |  -
+  RETR                                     |4.1.2.13       |x| | | | |  C
+  STOR                                     |4.1.2.13       |x| | | | |  C
+  STOU                                     |959 5.3.1      | | |x| | |  C
+  APPE                                     |4.1.2.13       |x| | | | |  C
+  ALLO                                     |959 5.3.1      | | |x| | |  C
+  REST                                     |959 5.3.1      | | |x| | |  E
+  RNFR                                     |4.1.2.13       |x| | | | |  C
+  RNTO                                     |4.1.2.13       |x| | | | |  C
+  ABOR                                     |959 5.3.1      | | |x| | |  E
+  DELE                                     |4.1.2.13       |x| | | | |  C
+  RMD                                      |4.1.2.13       |x| | | | |  C
+  MKD                                      |4.1.2.13       |x| | | | |  C
+  PWD                                      |4.1.2.13       |x| | | | |  C
+  LIST                                     |4.1.2.13       |x| | | | |  C
+  NLST                                     |4.1.2.13       |x| | | | |  C
+  SITE                                     |4.1.2.8        | | |x| | |  E
+  STAT                                     |4.1.2.13       |x| | | | |  C
+  SYST                                     |4.1.2.13       |x| | | | |  C
+  HELP                                     |4.1.2.13       |x| | | | |  C
+  NOOP                                     |4.1.2.13       |x| | | | |  C
+
+Footnotes:
+
+(1)  For the values shown earlier.
+(2)  Here m is number of bits in a memory word.
+(3)  Required for host with record-structured file system, optional
+     otherwise.
+
+</pre>
+
+## RFC-2228 - FTP Security Extensions
+
+Specifies several security extensions to the base FTP protocol defined
+in RFC-959. New commands: AUTH, ADAT, PROT, PBSZ, CCC, MIC, CONF, and
+ENC. New response codes: 232, 234, 235, 334, 335, 336, 431, 533, 534,
+535, 536, 537, 631, 632, and 633.
+
+<pre>
+AUTH    Yes    0.1.0    Authentication/Security Mechanism
+ADAT    No      ---     Authentication/Security Data
+PROT    Yes    0.1.0    Data Channel Protection Level
+PBSZ    Yes    0.1.0    Protection Buffer Size
+CCC     No      ---     Clear Command Channel
+MIC     No      ---     Integrity Protect Command
+CONF    No      ---     Confidentiality Protected Command
+ENC     No      ---     Privacy Protected Command
+</pre>
+
+## RFC-2389 - Feature negotiation mechanism for the File Transfer Protocol
+
+Introduces the new FEAT and OPTS commands.
+
+* Issued: August 1998
+* Status: PROPOSED STANDARD
+* [link](http://tools.ietf.org/rfc/rfc2389.txt)
+
+<pre>
+FEAT    Yes    0.6.0    List new supported commands
+OPTS    Yes    0.6.0    Set options for certain commands
+</pre>
+
+## RFC-2428 - FTP Extensions for IPv6 and NATs
+
+Introduces the new commands EPRT and EPSV extending FTP to enable its
+use over various network protocols, and the new response codes 522 and
+229.
+
+* Issued: September 1998
+* Status: PROPOSED STANDARD
+* [link](http://tools.ietf.org/rfc/rfc2428.txt)
+
+<pre>
+EPRT    Yes    0.9.0    Set active data connection over IPv4 or IPv6    
+EPSV    Yes    0.9.0    Set passive data connection over IPv4 or IPv6 
+</pre>
+
+##RFC-2577 - FTP Security Considerations
+
+Provides several configuration and implementation suggestions to
+mitigate some security concerns, including limiting failed password
+attempts and third-party "proxy FTP" transfers, which can be used in
+"bounce attacks".
+
+* Issued: May 1999
+* Status: INFORMATIONAL
+* [link](http://tools.ietf.org/rfc/rfc2577.txt)
+
+<pre>
+FTP bounce protection
+Restrict PASV/PORT to non-priv. ports     Yes    0.5.0
+Disconnect after so many wrong auths.     Yes    0.6.0
+Delay on invalid password                 Yes    0.6.0
+Per-source IP limit                       Yes    0.6.0
+Do not reject wrong usernames             Yes    0.1.0
+Port stealing protection                  Yes    0.1.0
+</pre>
+
+## RFC-2640 - Internationalization of the File Transfer Protocol
+
+Extends the FTP protocol to support multiple character sets, in
+addition to the original 7-bit ASCII. Introduces the new LANG command.
+
+* Issued: July 1999
+* Status: PROPOSED STANDARD
+* [link](http://tools.ietf.org/rfc/rfc2640.txt)
+
+<pre>
+LANG command     No      --- 
+UNICODE          No      ---
+</pre>
+
+## RFC-3659 - Extensions to FTP
+
+Four new commands are added: "SIZE", "MDTM", "MLST", and "MLSD". The existing command "REST" is modified.
+
+* Issued: March 2007
+* Status: PROPOSED STANDARD
+* Updates: [RFC-959](http://tools.ietf.org/rfc/rfc959.txt)
+* [link](http://tools.ietf.org/rfc/rfc3659.txt)
+
+<pre>
+MDTM command      Yes   ---   Get file's last modification time       
+MLSD command      No    ---   Get directory list in a standardized form.
+MLST command      No    ---   Get file information in a standardized form.
+SIZE command      Yes   ---   Get file size.
+TVSF mechanism    No    ---   Unix-like file system naming conventions
+Min. MLST facts   No    ---   
+GMT timestamps    Yes   ---
+</pre>
+
+##RFC-4217 - Securing FTP with TLS
+
+Provides a description on how to implement TLS as a security mechanism to secure FTP clients and/or servers.
+
+* Issued: October 2005
+* Status: STANDARD
+* Updates:
+  [RFC-959](http://tools.ietf.org/rfc/rfc959.txt)
+  [RFC-2246](http://tools.ietf.org/rfc/rfc2246.txt)
+  [RFC-2228](http://tools.ietf.org/rfc/rfc2228.txt)
+* [link](http://tools.ietf.org/rfc/rfc4217.txt)
+
+<pre>
+AUTH    Yes    0.1.0    Authentication/Security Mechanism
+CCC     No      ---     Clear Command Channel
+PBSZ    Yes    0.1.0    Protection Buffer Size
+PROT    Yes    0.1.0    Data Channel Protection Level.
+                        Support only "Private" level
+</pre>

data/examples/example.rb

@@ -0,0 +1,275 @@
+#!/usr/bin/env ruby
+
+unless $:.include?(File.dirname(__FILE__) + '/../lib')
+  $:.unshift(File.dirname(__FILE__) + '/../lib')
+end
+
+require 'ftpd'
+require 'ipaddr'
+require 'optparse'
+
+module Example
+
+  # Command-line option parser
+
+  class Arguments
+
+    attr_reader :account
+    attr_reader :auth_level
+    attr_reader :debug
+    attr_reader :eplf
+    attr_reader :interface
+    attr_reader :password
+    attr_reader :port
+    attr_reader :read_only
+    attr_reader :session_timeout
+    attr_reader :tls
+    attr_reader :user
+
+    def initialize(argv)
+      @interface = '127.0.0.1'
+      @tls = :explicit
+      @port = 0
+      @auth_level = 'password'
+      @user = ENV['LOGNAME']
+      @password = ''
+      @account = ''
+      @session_timeout = default_session_timeout
+      @log = nil
+      op = option_parser
+      op.parse!(argv)
+    rescue OptionParser::ParseError => e
+      $stderr.puts e
+      exit(1)
+    end
+
+    private
+
+    def option_parser
+      op = OptionParser.new do |op|
+        op.on('-p', '--port N', Integer, 'Bind to a specific port') do |t|
+          @port = t
+        end
+        op.on('-i', '--interface IP', 'Bind to a specific interface') do |t|
+          @interface = t
+        end
+        op.on('--tls [TYPE]', [:off, :explicit, :implicit],
+              'Select TLS support (off, explicit, implicit)',
+              'default = off') do |t|
+          @tls = t
+        end
+        op.on('--eplf', 'LIST uses EPLF format') do |t|
+          @eplf = t
+        end 
+        op.on('--read-only', 'Prohibit put, delete, rmdir, etc.') do |t|
+          @read_only = t
+        end
+        op.on('--auth [LEVEL]', [:user, :password, :account],
+              'Set authorization level (user, password, account)',
+              'default = password') do |t|
+          @auth_level = t
+        end
+        op.on('-U', '--user NAME', 'User for authentication',
+              'defaults to current user') do |t|
+          @user = t
+        end
+        op.on('-P', '--password PW', 'Password for authentication',
+              'defaults to empty string') do |t|
+          @password = t
+        end
+        op.on('-A', '--account PW', 'Account for authentication',
+              'defaults to empty string') do |t|
+          @account = t
+        end
+        op.on('--timeout SEC', Integer, 'Session idle timeout',
+              "defaults to #{default_session_timeout}") do |t|
+          @session_timeout = t
+        end
+        op.on('-d', '--debug', 'Write server debug log to stdout') do |t|
+          @debug = t
+        end
+      end
+    end
+
+    def default_session_timeout
+      Ftpd::FtpServer::DEFAULT_SESSION_TIMEOUT
+    end
+
+  end
+end
+
+module Example
+
+  # The FTP server requires and instance of a _driver_ which can
+  # authenticate users and create a file system drivers for a given
+  # user.  You can use this as a template for creating your own
+  # driver.
+
+  class Driver
+
+    # Your driver's initialize method can be anything you need.  Ftpd
+    # does not create an instance of your driver.
+
+    def initialize(user, password, account, data_dir, read_only)
+      @user = user
+      @password = password
+      @account = account
+      @data_dir = data_dir
+      @read_only = read_only
+    end
+
+    # Return true if the user should be allowed to log in.
+    # @param user [String]
+    # @param password [String]
+    # @param account [String]
+    # @return [Boolean]
+    #
+    # Depending upon the server's auth_level, some of these parameters
+    # may be nil.  A parameter with a nil value is not required for
+    # authentication.  Here are the parameters that are non-nil for
+    # each auth_level:
+    # * :user (user)
+    # * :password (user, password)
+    # * :account (user, password, account)
+
+    def authenticate(user, password, account)
+      user == @user &&
+        (password.nil? || password == @password) &&
+        (account.nil? || account == @account)
+    end
+
+    # Return the file system to use for a user.
+    # @param user [String]
+    # @return A file system driver that quacks like {Ftpd::DiskFileSystem}
+
+    def file_system(user)
+      if @read_only
+        Ftpd::ReadOnlyDiskFileSystem
+      else
+        Ftpd::DiskFileSystem
+      end.new(@data_dir)
+    end
+
+  end
+end
+
+module Example
+  class Main
+
+    include Ftpd::InsecureCertificate
+
+    def initialize(argv)
+      @args = Arguments.new(argv)
+      @data_dir = Ftpd::TempDir.make
+      create_files
+      @driver = Driver.new(user, password, account,
+                           @data_dir, @args.read_only)
+      @server = Ftpd::FtpServer.new(@driver)
+      configure_server
+      @server.start
+      display_connection_info
+      create_connection_script
+    end
+
+    def run
+      wait_until_stopped
+    end
+
+    private
+
+    def configure_server
+      @server.interface = @args.interface
+      @server.port = @args.port
+      @server.tls = @args.tls
+      @server.certfile_path = insecure_certfile_path
+      if @args.eplf
+        @server.list_formatter = Ftpd::ListFormat::Eplf
+      end
+      @server.auth_level = auth_level
+      @server.session_timeout = @args.session_timeout
+      @server.log = make_log
+    end
+
+    def auth_level
+      Ftpd.const_get("AUTH_#{@args.auth_level.upcase}")
+    end
+
+    def create_files
+      create_file 'README',
+      "This file, and the directory it is in, will go away\n"
+      "When this example exits.\n"
+    end
+
+    def create_file(path, contents)
+      full_path = File.expand_path(path, @data_dir)
+      FileUtils.mkdir_p File.dirname(full_path)
+      File.open(full_path, 'w') do |file|
+        file.write contents
+      end
+    end
+
+    def display_connection_info
+      puts "Interface: #{@server.interface}"
+      puts "Port: #{@server.bound_port}"
+      puts "User: #{user.inspect}"
+      puts "Pass: #{password.inspect}" if auth_level >= Ftpd::AUTH_PASSWORD
+      puts "Account: #{account.inspect}" if auth_level >= Ftpd::AUTH_ACCOUNT
+      puts "TLS: #{@args.tls}"
+      puts "Directory: #{@data_dir}"
+      puts "URI: #{uri}"
+      puts "PID: #{$$}"
+    end
+
+    def uri
+      "ftp://#{connection_host}:#{@server.bound_port}"
+    end
+
+    def create_connection_script
+      command_path = '/tmp/connect-to-example-ftp-server.sh'
+      File.open(command_path, 'w') do |file|
+        file.puts "#!/bin/bash"
+        file.puts "ftp $FTP_ARGS #{connection_host} #{@server.bound_port}"
+      end
+      system("chmod +x #{command_path}")
+      puts "Connection script written to #{command_path}"
+    end
+
+    def wait_until_stopped
+      puts "FTP server started.  Press ENTER or c-C to stop it"
+      $stdout.flush
+      begin
+        gets
+      rescue Interrupt
+        puts "Interrupt"
+      end
+    end
+
+    def user
+      @args.user
+    end
+
+    def password
+      @args.password
+    end
+
+    def account
+      @args.account
+    end
+
+    def make_log
+      @args.debug && Logger.new($stdout)
+    end
+
+    def connection_host
+      addr = IPAddr.new(@server.interface)
+      if addr.ipv6?
+        '::1'
+      else
+        '127.0.0.1'
+      end
+    end
+
+  end
+end
+
+Example::Main.new(ARGV).run if $0 == __FILE__