ftpd 0.5.0 → 0.6.0

data/Changelog.md

@@ -1,3 +1,25 @@
+### 0.6.0
+
+Enhancements
+
+* Configurable maximum connections (defaults to unlimited).
+* Configurable maximum connections per IP (defaults to unlimited).
+* Configurable disconnect after too many failed login attempts
+  (defaults to unlimited)
+* Delay after failed login (configurable).
+
+API Changes
+
+* Changes to {Ftpd::FtpServer} attributes should now only be made
+  before calling #start.  The effect of setting these attributes
+  after #start is undefined.
+* Added {Ftpd::FtpServer#max_connections}
+* Added {Ftpd::FtpServer#max_connections_per_ip}
+* Added {Ftpd::FtpServer#max_failed_logins}
+* Added {Ftpd::FtpServer#failed_login_delay}
+* Support FEAT (feature list)
+* Support OPTS (set options)
+
 ### 0.5.0
 
 Bug fixes
@@ -70,10 +92,10 @@ rewritten.  It no longer shells out to ls, which removes potential
 command injection security holes, and improves prospects for
 portability.
 
-* Removed {Ftpd::DiskFileSystem::Ls}
-* Removed {Ftpd::DiskFileSystem::NameList}.  NLIST now uses the
+* Removed Ftpd::DiskFileSystem::Ls
+* Removed Ftpd::DiskFileSystem::NameList.  NLIST now uses the
   functions in {Ftpd::DiskFileSystem::List}.
-* Removed {Ftpd::DiskFileSystem::List#list}.  The formatting of
+* Removed Ftpd::DiskFileSystem::List#list.  The formatting of
   directory output is now done by ftpd, not by the file system driver.
 * Added {Ftpd::DiskFileSystem::List#file_info}, used by LIST.
 * Added {Ftpd::DiskFileSystem::List#dir}, used by LIST and NLST.

data/Gemfile

@@ -5,7 +5,6 @@ gem 'memoizer', '~> 1.0.1'
 group :development do
   gem 'cucumber'
   gem 'double-bag-ftps', :git => 'git@github.com:wconrad/double-bag-ftps.git'
-  gem 'fuubar-cucumber'
   gem 'jeweler'
   gem 'rake'
   gem 'redcarpet'

data/Gemfile.lock

@@ -14,9 +14,6 @@ GEM
       gherkin (~> 2.11.0)
       json (>= 1.4.6)
     diff-lcs (1.2.1)
-    fuubar-cucumber (0.0.18)
-      cucumber (~> 1.2.0)
-      ruby-progressbar (~> 1.0.0)
     gherkin (2.11.6)
       json (>= 1.7.6)
     git (1.2.5)
@@ -39,7 +36,6 @@ GEM
     rspec-expectations (2.13.0)
       diff-lcs (>= 1.1.3, < 2.0)
     rspec-mocks (2.13.0)
-    ruby-progressbar (1.0.2)
     timecop (0.5.9.2)
     yard (0.8.5.2)
 
@@ -49,7 +45,6 @@ PLATFORMS
 DEPENDENCIES
   cucumber
   double-bag-ftps!
-  fuubar-cucumber
   jeweler
   memoizer (~> 1.0.1)
   rake

data/README.md

@@ -1,18 +1,34 @@
-# FTPD
+# Ftpd
 
 ftpd is a pure Ruby FTP server library.  It supports implicit and
 explicit TLS, passive and active mode, and is unconditionally
-complaint per RFC-1123.  It an be used as part of a test fixture or
+compliant per [RFC-1123][1].  It an be used as part of a test fixture or
 embedded in a program.
 
 ## A note about this README
 
-This readme, and the other files, contains Yardoc markup, especially
-for links to the API docs; those links don't display properly on
-github.  You'll find a properly rendered version
-[on rubydoc.info](http://rubydoc.info/gems/ftpd)
+This readme, and other files, contains Yardoc markup, especially for
+links to the API docs; those links don't display properly on github.
+You'll find a properly rendered version [on
+rubydoc.info](http://rubydoc.info/gems/ftpd)
 
-## HELLO WORLD
+## The state of this library
+
+Ftpd has been used for many years to test FTP clients, and is stable
+and reliable for that purpose.  However, it was not originally
+intended to be part of a publically accessible FTP server.  I would be
+cautious in using it in an untrusted environment due to the
+probability that it contains critical flaws (or even security
+vulnarabilities) that have not been discovered in its use as a test
+harness.
+
+In this 0.X.X release, the API is changing at least a little with
+almost every release.  If you need to keep those changes from
+impacting you (or at least want to let many of them build up before
+you have to deal with them), then lock your Gemfile down to a minor
+release (e.g. :version => '~> 0.5.0').
+
+## Hello World
 
 This is examples/hello_world.rb, a bare minimum FTP server.  It allows
 any user/password, and serves files in a temporary directory.  It
@@ -48,7 +64,7 @@ binds to an ephemeral port on the local interface:
 A more full-featured example that allows TLS and takes options is in
 examples/example.rb
 
-## DRIVER
+## Driver
 
 Ftpd's dynamic behavior such as authentication and file retrieval is
 controlled by a driver that you supply.  The Driver class in the
@@ -63,7 +79,7 @@ driver will do.  Here are the methods your driver needs:
 * {Example::Driver#authenticate authenticate}
 * {Example::Driver#file_system file_system}
 
-## FILE SYSTEM
+## File System
 
 The file system object that the driver supplies to Ftpd is Ftpd's
 gateway to the logical file system.  Ftpd doesn't know or care whether
@@ -109,7 +125,7 @@ Ftpd includes a disk based file system:
 
     end
 
-*Warning*: The DiskFileSystem allows file and directory modification
+**Warning**: The DiskFileSystem allows file and directory modification
 including writing, renaming, deleting, etc.  If you want a read-only
 file system, then use {Ftpd::ReadOnlyDiskFileSystem} instead.
 
@@ -125,35 +141,62 @@ The DiskFileSystem is composed out of modules:
 * {Ftpd::DiskFileSystem::Rmdir Rmdir} - Directory removal
 * {Ftpd::DiskFileSystem::Write Write} - File writing
 
-For example, to create a custom file system that allows reading and
-writing only, then:
+You can use these modules to create a custom disk file system that
+allows only the operations you want, or which mixes the predefined
+modules with your customizations, as in this silly example that allows
+uploads but then throws them away.
+
+    class BlackHole
+      def write(ftp_path, contents)
+      end
+    end
 
     class CustomDiskFileSystem
       include DiskFileSystem::Base
-      include DiskFileSystem::List
       include DiskFileSystem::Read
-      include DiskFileSystem::Write
+      include BlackHole
     end
 
-    class Driver
-
-      ...
+## Configuration
 
-      def file_system(user)
-        CustomDiskFileSystem('/var/lib/ftp')
-      end
+Configuration is done via accessors on {Ftpd::FtpServer}.  For
+example, to set the session timeout to 10 minutes:
 
-    end
+      server = Ftpd::FtpServer.new(driver)
+      server.session_timeout = 10 * 60
+      server.start
 
-## LIST output format
+You can set any of these attributes before starting the server:
+
+* {Ftpd::FtpServer#allow_low_data_ports}
+* {Ftpd::FtpServer#auth_level}
+* {Ftpd::FtpServer#failed_login_delay}
+* {Ftpd::FtpServer#list_formatter}
+* {Ftpd::FtpServer#log}
+* {Ftpd::FtpServer#max_connections_per_ip}
+* {Ftpd::FtpServer#max_connections}
+* {Ftpd::FtpServer#max_failed_logins}
+* {Ftpd::FtpServer#response_delay}
+* {Ftpd::FtpServer#server_name}
+* {Ftpd::FtpServer#server_version}
+* {Ftpd::FtpServer#session_timeout}
+* {Ftpd::Server#interface}
+* {Ftpd::Server#port}
+* {Ftpd::TlsServer#certfile_path}
+* {Ftpd::TlsServer#tls}
+
+### LIST output format
 
 By default, the LIST command uses Unix "ls -l" formatting:
 
     -rw-r--r-- 1 user     group        1234 Mar  3 08:38 foo
 
-To switch to
-[Easily Parsed LIST format (EPLF)](http://cr.yp.to/ftp/list/eplf.html)
-format:
+An alternative to "ls -l" formatting is [Easily Parsed LIST format
+(EPLF)](http://cr.yp.to/ftp/list/eplf.html) format:
+
+    +r,s1234,m1362325080\tfoo
+
+to configure Ftpd for EPLF formatting:
 
     ftp_server.list_formatter = Ftpd::ListFormat::Eplf
 
@@ -167,35 +210,36 @@ And register your class with the ftp_server before starting it:
 
     ftp_server.list_formatter = MyListFormatter
 
-## DEBUGGING
+### Logging
+
+Ftpd can write to an instance of {Logger} that you provide.  To log to
+standard out:
 
-Ftpd can write debugging information (essentially a transcript of its
-conversation with a client) to a file.  If you turn the debug flag on,
-the server will write debug information to stdout:
+    server.log = Logger.new($stdout)
 
-    server = Ftpd::FtpServer.new(driver)
-    server.debug = true
+To log to a file:
 
-If you want to send the debug output to somewhere else, set
-debug_path:
+    server.log = Logger.new('/tmp/ftpd.log')
 
-    server.debug_path = '/tmp/ftp_session'
+## Standards Compliance
 
-Debug output can also be enabled by setting the environment variable
-FTPD_DEBUG to a non-zero value.  This is a convenient way to get debug
-output without having to change any code.
+* Unconditionally compliant per [RFC-1123][1] (Requirements for
+  Internet Hosts).
 
-## STANDARDS COMPLIANCE
+* Implements all of the security recommendations in
+  [RFC-2577](http://tools.ietf.org/rfc/rfc2577.txt) (FTP Security
+  Considerations).
 
-Ftpd is fully unconditionally compliant per [RFC-1123 Requirements for
-Internet Hosts](http://tools.ietf.org/rfc/rfc1123.txt).
+* Implements [RFC-2389](http://tools.ietf.org/rfc/rfc2389.txt)
+  (Feature negotiation mechanism for the File Transfer Protocol)
 
-Ftpd implements enough of [RFC-4217 Securing FTP with
-TLS](http://tools.ietf.org/rfc/rfc4217.txt) to get by.
+* Implements enough of
+  [RFC-4217](http://tools.ietf.org/rfc/rfc4217.txt) (Securing FTP with
+  TLS) to get by.
 
 See [RFC Compliance](doc/rfc-compliance.md) for details
 
-## RUBY COMPATABILITY
+## Ruby Compatability
 
 The tests pass with these Rubies:
 
@@ -203,9 +247,9 @@ The tests pass with these Rubies:
 * ruby-1.9.3-p392
 * ruby-2.0.0-p0
 
-## DEVELOPMENT
+## Development
 
-### TESTS
+### Tests
 
 To run the cucumber (functional) tests:
 
@@ -229,25 +273,37 @@ To force features to write the server log to stdout:
 
 ### Example
 
-To run the stand-alone example:
+The stand-alone example is good for manually testing Ftpd with any FTP
+client.  To run the stand-alone example:
 
     $ examples/example.rb
 
 The example prints its port, username and password to the console.
-You can connect to the stand-alone example with any FTP client.  This
-is useful when testing how the server responds to a given FTP client.
+You can connect to the stand-alone example with any FTP client.
 
-## ORIGIN
+example.rb has many options.  To see them:
+
+    $ examples/example.rb -h
+
+### Contributing
+
+1. Fork it
+2. Create your feature branch (`git checkout -b my-new-feature`)
+3. Commit your changes (`git commit -am 'Add some feature'`)
+4. Push to the branch (`git push origin my-new-feature`)
+5. Create new Pull Request
+
+## Origin
 
 I created ftpd to support the test framework I wrote for Databill,
 LLC, which has given its kind permission to donate it to the
 community.
 
-## WHOAMI
+## Whoami
 
 Wayne Conrad <wconrad@yagni.com>
 
-## CREDITS
+## Credits
 
 Thanks to Databill, LLC, which supported the creation of this library,
 and granted permission to donate it to the community.
@@ -258,3 +314,5 @@ and granted permission to donate it to the community.
 * [RFC compliance](doc/rfc-compliance.md)
 * [References](doc/references.md)
 * [Benchmarks](doc/benchmarks.md)
+
+[1]: http://tools.ietf.org/rfc/rfc1123.txt

data/VERSION

@@ -1 +1 @@
-0.5.0
+0.6.0

data/doc/benchmarks.md

@@ -1,7 +1,6 @@
 # Benchmarks
 
-Benchmarks using pyftpd's [benchmark
-script](http://pyftpdlib.googlecode.com/svn/trunk/test/bench.py) and
+Benchmarks using pyftpd's benchmark script and
 [procedures](http://code.google.com/p/pyftpdlib/wiki/Benchmarks).
 
 ## Results
@@ -75,7 +74,9 @@ proftpd or pyftpdlib.
 
 ### Benchmark command
 
-    $ python bench.py  -u <USER> -p <PASS> -H localhost -p <PORT> -b all -n 200 -k <PID>
+bench.py needs psutil.  Under Debian, install _python-psutil_.
+
+    pyftpdlib-1.0.1/test$ python bench.py  -u <USER> -p <PASS> -H localhost -P <PORT> -b all -n 200 -k <PID>
 
 ### Proftpd
 

data/doc/references.md

@@ -40,7 +40,7 @@ chronological order, the more useful ones are:
   FTP
 
 * [RFC-4217](http://tools.ietf.org/rfc/rfc4217.txt) -
-  Internationalization of the File Transfer Protocol
+  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

data/doc/rfc-compliance.md

@@ -104,10 +104,10 @@ 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| | | |
-Sender assume 110 replies are synchronous  |4.1.3.4        | | | | |x|
-                                           |               | | | | | |
-Support TYPE:                              |               | | | | | |
+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
@@ -115,17 +115,17 @@ Support TYPE:                              |               | | | | | |
   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:                              |               | | | | | |
+                                           |               | | | | | |  -
+Support MODE:                              |               | | | | | |  -
   Stream                                   |4.1.2.13       |x| | | | |  C
   Block                                    |959 3.4.2      | | |x| | |  E
-                                           |               | | | | | |
-Support STRUCTURE:                         |               | | | | | |
+                                           |               | | | | | |  -
+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:                          |               | | | | | |
+                                           |               | | | | | |  -
+Support commands:                          |               | | | | | |  -
   USER                                     |4.1.2.13       |x| | | | |  C
   PASS                                     |4.1.2.13       |x| | | | |  C
   ACCT                                     |4.1.2.13       |x| | | | |  C
@@ -134,13 +134,13 @@ Support commands:                          |               | | | | | |
   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
@@ -198,8 +198,8 @@ Introduces the new FEAT and OPTS commands.
 * [link](http://tools.ietf.org/rfc/rfc2389.txt)
 
 <pre>
-FEAT    No      ---     List new supported commands
-OPTS    No      ---     Set options for certain commands
+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
@@ -231,11 +231,11 @@ attempts and third-party "proxy FTP" transfers, which can be used in
 <pre>
 FTP bounce protection
 Restrict PASV/PORT to non-priv. ports     Yes    0.5.0
-Disconnect after so many wrong auths.     No      ---
-Delay on invalid password                 No      ---
-Per-source IP limit                       No      ---
+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                  No      ---
+Port stealing protection                  Yes    0.1.0
 </pre>
 
 ## RFC-2640 - Internationalization of the File Transfer Protocol

data/examples/example.rb

@@ -214,6 +214,7 @@ module Example
       puts "TLS: #{@args.tls}"
       puts "Directory: #{@data_dir}"
       puts "URI: ftp://#{HOST}:#{@server.bound_port}"
+      puts "PID: #{$$}"
     end
 
     def create_connection_script