ftpd 0.3.2 → 0.4.0

data/.yardopts

@@ -1,6 +1,7 @@
 -o doc-api
 --exclude '[~#]$'
 --readme README.md
+--files Changelog.md
 --files doc/*.md
 lib/**/*.rb
 examples/example.rb

data/Changelog.md

@@ -1,8 +1,32 @@
-### 0.3.2
+### 0.4.0
 
 Enhancements
 
 * Improved driver and file-system documentation.
+* Added {Ftpd::ReadOnlyDiskFileSystem read only disk file system}
+* Example can be run with a read-only file system
+* Supports three different levels of authentication:
+  * User
+  * User + Password
+  * User + Password + Account
+* Added --auth switch to the example to select the authentication
+  level.
+* Support APPE
+* Support TYPE "A T" (ASCII/Telnet)
+* Support TYPE "LOCAL 8"
+* Added switches to example to set authentication values
+  * --user
+  * --password
+  * --account
+
+API changes
+
+* {Example::Driver#authenticate authenticate} now takes three
+  parameters (user, password, account).  For compatability, it can be
+  defined to take only two, provided you are not doing account
+  authentication.
+* Added {Ftpd::FtpServer#auth_level} option
+* Added {Ftpd::DiskFileSystem::Append}
 
 ### 0.3.1
 

data/README.md

@@ -8,7 +8,8 @@ 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.  You'll find a properly rendered version
+for links to the API docs; those links don't display properly on
+github.  You'll find a properly rendered version
 {http://rubydoc.info/gems/ftpd on rubydoc.info}
 
 ## HELLO WORLD
@@ -91,6 +92,77 @@ Here are the methods a file system may expose:
 * {Ftpd::DiskFileSystem::List#dir dir}
 * {Ftpd::DiskFileSystem::Rename#rename rename}
 
+### DiskFileSystem
+
+Ftpd includes a disk based file system:
+
+    class Driver
+
+      ...
+
+      def file_system(user)
+        Ftpd::DiskFileSystem.new('/var/lib/ftp')
+      end
+
+    end
+
+*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.
+
+The DiskFileSystem is composed out of modules:
+
+* {Ftpd::DiskFileSystem::Base Base} - You will need this
+* {Ftpd::DiskFileSystem::Delete Delete} - File deletion
+* {Ftpd::DiskFileSystem::List List} - Directory listing
+* {Ftpd::DiskFileSystem::Mkdir Mkdir} - Directory creation
+* {Ftpd::DiskFileSystem::Read Read} - File reading
+* {Ftpd::DiskFileSystem::Rename Rename} - File renaming
+* {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:
+
+    class CustomDiskFileSystem
+      include DiskFileSystem::Base
+      include DiskFileSystem::List
+      include DiskFileSystem::Read
+      include DiskFileSystem::Write
+    end
+
+    class Driver
+
+      ...
+
+      def file_system(user)
+        CustomDiskFileSystem('/var/lib/ftp')
+      end
+
+    end
+
+## 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
+{http://cr.yp.to/ftp/list/eplf.html Easily Parsed LIST format (EPLF)}
+format:
+
+    ftp_server.list_formatter = Ftpd::ListFormat::Eplf
+
+To create your own custom formatter, create a class with these
+methods:
+
+* {Ftpd::ListFormat::Ls#initialize initialize}
+* {Ftpd::ListFormat::Ls#to_s to_s}
+
+And register your class with the ftp_server before starting it:
+
+    ftp_server.list_formatter = MyListFormatter
+
 ## DEBUGGING
 
 Ftpd can write debugging information (essentially a transcript of its
@@ -111,16 +183,25 @@ output without having to change any code.
 
 ## LIMITATIONS
 
-Ftpd is not yet RFC compliant.  It does most of RFC969, and enough TLS
-to get by.  {file:doc/rfc.md Here} is a list of RFCs, indicating how
-much of each Ftpd complies with.
+Ftpd is not fully RFC compliant.  It does most of RFC969, and enough
+TLS to get by.  {file:doc/rfc.md Here} is a list of RFCs, indicating
+how much of each Ftpd complies with.
+
+RFC does not meet the following
+[RFC-1123](http://tools.ietf.org/rfc/rfc1123.txt) "MUST" requrements.
+If FTPD met these requirements, but did not meet the "SHOULD"
+requirements, it would be "conditionally compliant":
+
+* Server-FTP handle Telnet options
+* Support command STAT
+
+RFC does not meet the following
+[RFC-1123](http://tools.ietf.org/rfc/rfc1123.txt)
+"SHOULD" requrements.  If FTPD met both the "MUST" and the "SHOULD"
+requirements, it would be "unconditionally compliant":
 
-To bind the server to an external interface, the interface must be set
-to the public IP of that interface (e.g. "1.2.3.4"), not to "0.0.0.0".
-That's because the interface IP is used both for binding server ports,
-_and_ for advertising to the client which IP to connect to.  Binding
-to 0.0.0.0 will work fine, but when the client tries to connect to
-0.0.0.0, it won't get to the server.
+* Idle timeout in server-FTP
+* Configurable idle timeout
 
 ## RUBY COMPATABILITY
 

data/VERSION

@@ -1 +1 @@
-0.3.2
+0.4.0

data/doc/rfc-compliance.md

@@ -22,10 +22,10 @@ pyftpdlib is what every FTP library wants to be when it grows up.
 Commands supported:
 
     ABOR    No      ---     Abort transfer
-    ACCT    No      ---     Specify user's account
+    ACCT    Yes    0.4.0    Specify user's account
     ALLO    Yes    0.2.0    Allocate storage space
                             Treated as a NOOP
-    APPE    No      ---     Append to file
+    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    
@@ -87,18 +87,18 @@ with "C" where FTPD complies, or "E" where compliance is not required.
                                            |               |T|D|Y|O|O|t
 FEATURE                                    |SECTION        | | | |T|T|e
 -------------------------------------------|---------------|-|-|-|-|-|--
-Implement TYPE T if same as TYPE N         |4.1.2.2        | |x| | | |  
-File/Record transform invertible if poss.  |4.1.2.4        | |x| | | |  
+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| | | |  
+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| | |
+  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| | | | |
 Handle "Experimental" directory cmds       |4.1.3.1        | |x| | | |  C
@@ -109,30 +109,30 @@ Sender assume 110 replies are synchronous  |4.1.3.4        | | | | |x|
                                            |               | | | | | |
 Support TYPE:                              |               | | | | | |
   ASCII - Non-Print (AN)                   |4.1.2.13       |x| | | | |  C
-  ASCII - Telnet (AT) -- if same as AN     |4.1.2.2        | |x| | | |
-  ASCII - Carriage Control (AC)            |959 3.1.1.5.2  | | |x| | |
-  EBCDIC - (any form)                      |959 3.1.1.2    | | |x| | |
+  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| | | | |
-  LOCAL m                                  |4.1.2.1        | | |x| | |2
+  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| | |
+  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| |
+  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| | | | |
+  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| | |
-  REIN                                     |959 5.3.1      | | |x| | |
+  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
@@ -144,19 +144,19 @@ Support commands:                          |               | | | | | |
   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| | | | |
+  APPE                                     |4.1.2.13       |x| | | | |  C
   ALLO                                     |959 5.3.1      | | |x| | |  C
-  REST                                     |959 5.3.1      | | |x| | |
+  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| | |
+  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| | |
+  SITE                                     |4.1.2.8        | | |x| | |  E
   STAT                                     |4.1.2.13       |x| | | | |
   SYST                                     |4.1.2.13       |x| | | | |  C
   HELP                                     |4.1.2.13       |x| | | | |  C

data/examples/example.rb

@@ -13,15 +13,24 @@ module Example
 
   class Arguments
 
+    attr_reader :account
+    attr_reader :auth_level
     attr_reader :eplf
     attr_reader :interface
+    attr_reader :password
     attr_reader :port
+    attr_reader :read_only
     attr_reader :tls
+    attr_reader :user
 
     def initialize(argv)
       @interface = 'localhost'
       @tls = :explicit
       @port = 0
+      @auth_level = 'password'
+      @user = ENV['LOGNAME']
+      @password = ''
+      @account = ''
       op = option_parser
       op.parse!(argv)
     rescue OptionParser::ParseError => e
@@ -40,11 +49,32 @@ module Example
           @interface = t
         end
         op.on('--tls [TYPE]', [:off, :explicit, :implicit],
-              'Select TLS support (off, explicit, implicit)') do |t|
+              '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
       end
     end
@@ -64,19 +94,32 @@ module Example
     # Your driver's initialize method can be anything you need.  Ftpd
     # does not create an instance of your driver.
 
-    def initialize(user, password, data_dir)
+    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]
-
-    def authenticate(user, password)
-      user == @user && password == @password
+    #
+    # 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.
@@ -84,7 +127,11 @@ module Example
     # @return A file system driver that quacks like {Ftpd::DiskFileSystem}
 
     def file_system(user)
-      Ftpd::DiskFileSystem.new(@data_dir)
+      if @read_only
+        Ftpd::ReadOnlyDiskFileSystem
+      else
+        Ftpd::DiskFileSystem
+      end.new(@data_dir)
     end
 
   end
@@ -99,7 +146,8 @@ module Example
       @args = Arguments.new(argv)
       @data_dir = Ftpd::TempDir.make
       create_files
-      @driver = Driver.new(user, password, @data_dir)
+      @driver = Driver.new(user, password, account,
+                           @data_dir, @args.read_only)
       @server = Ftpd::FtpServer.new(@driver)
       @server.interface = @args.interface
       @server.port = @args.port
@@ -108,6 +156,7 @@ module Example
       if @args.eplf
         @server.list_formatter = Ftpd::ListFormat::Eplf
       end
+      @server.auth_level = auth_level
       @server.start
       display_connection_info
       create_connection_script
@@ -121,6 +170,10 @@ module Example
 
     HOST = 'localhost'
 
+    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"
@@ -138,8 +191,9 @@ module Example
     def display_connection_info
       puts "Interface: #{@server.interface}"
       puts "Port: #{@server.bound_port}"
-      puts "User: #{user}"
-      puts "Pass: #{password}"
+      puts "User: #{user.inspect}"
+      puts "Pass: #{password.inspect}" if auth_level >= Ftpd::AUTH_PASSWORD
+      puts "Acctount: #{account.inspect}" if auth_level >= Ftpd::AUTH_ACCOUNT
       puts "TLS: #{@args.tls}"
       puts "Directory: #{@data_dir}"
       puts "URI: ftp://#{HOST}:#{@server.bound_port}"
@@ -166,11 +220,15 @@ module Example
     end
 
     def user
-      ENV['LOGNAME']
+      @args.user
     end
 
     def password
-      ''
+      @args.password
+    end
+
+    def account
+      @args.account
     end
 
   end

data/features/example/read_only.feature

@@ -0,0 +1,63 @@
+Feature: Example
+
+  As a programmer
+  I want to start a read-only server
+  So that nobody can modify the file system I expose
+
+  Background:
+    Given the example has argument "--read-only"
+    And the example server is started
+
+  Scenario: Fetch README
+    Given a successful login
+    When the client successfully gets text "README"
+    Then the local file "README" should match the remote file
+
+  Scenario: Fetch README
+    Given a successful login
+    When the client successfully gets text "README"
+    Then the local file "README" should match the remote file
+
+  Scenario: List
+    Given a successful login
+    When the client successfully lists the directory
+    Then the file list should be in long form
+    And the file list should contain "README"
+
+  Scenario: Name List
+    Given a successful login
+    When the client successfully name-lists the directory
+    Then the file list should be in short form
+    And the file list should contain "README"
+
+  Scenario: Put
+    Given a successful login
+    And the client has file "foo"
+    When the client puts text "foo"
+    Then the server returns an unimplemented command error
+
+  Scenario: Put unique
+    Given a successful login
+    And the client has file "foo"
+    When the client stores unique "foo"
+    Then the server returns an unimplemented command error
+
+  Scenario: Delete
+    Given a successful login
+    When the client deletes "README"
+    Then the server returns an unimplemented command error
+
+  Scenario: Mkdir
+    Given a successful login
+    When the client makes directory "foo"
+    Then the server returns an unimplemented command error
+
+  Scenario: Rename
+    Given a successful login
+    When the client renames "README" to "foo"
+    Then the server returns an unimplemented command error
+
+  Scenario: Rmdir
+    Given a successful login
+    When the client removes directory "foo"
+    Then the server returns an unimplemented command error