Skip to content

HTTPS clone URL

Subversion checkout URL

You can clone with
or
.
Download ZIP
Lightweight FTP server framework built on the EventMachine
Ruby
branch: master

This branch is 6 commits ahead, 16 commits behind yob:master

Fetching latest commit…

Cannot retrieve the latest commit at this time

Failed to load latest commit information.
bin
examples
lib
spec
.gitignore
.rspec
.travis.yml
CHANGELOG
Gemfile
Guardfile
MIT-LICENSE
README.markdown
Rakefile
TODO
em-ftpd.gemspec

README.markdown

em-ftpd

A mini-FTP server framework built on top of the EventMacine gem. By providing a simple driver class that responds to a handful of methods you can have a complete FTP server.

The library is extracted from real world situations where an FTP interface was required to sit in front of a non-filesystem persistence layer.

Some sample use cases include persisting data to:

  • an Amazon S3 bucket
  • a relational database
  • redis
  • memory

The examples directory contains a demonstration of in memory persistence.

Installation

gem install em-ftpd

Usage

To boot an FTP server you will need to provide a driver that speaks to your persistence layer.

Create a config.rb file that loads the driver and then configures the server

require 'my_fancy_driver'

driver    MyFancyDriver
user      'ftp'
group     'ftp'

Run your server like so:

em-ftpd config.rb

Config File

Valid options for the config file are:

  • user [name of system user to run the process as]
  • group [name of group to run the process as]
  • daemonise [true/false]
  • name [a string to include in the process description]
  • pid_file [a path to save the pid to. Useful in conjunction with daemonise]
  • port [the TCP port to bind to. Defaults to 21]
  • driver [the class that connects to the persistance layer]
  • driver_args [array of any arguments that need to be passed to the driver constructor]
  • private_key_file [the path to the private ssl key. This config is needed if you want AUTH TLS to work.]
  • cert_chain_file [the path to the certificate chain file. This config is needed if you want AUTH TLS to work.]
  • enforce_tls [true/false. True if the user needs to use AUTH TLS before logging in. If you set this to true private_key_file and cert_chain_file must be set also.]
  • enforce_data_tls [true/false. True if server should enforce encrypted data channels. If you set this to true private_key_file and cert_chain_file must be set also.]

The Driver Contract

The driver MUST have the following methods. Each method MUST accept a block and yield the appropriate value:

authenticate(user, pass, &block)
- boolean indicating if the provided details are valid

bytes(path, &block)
- an integer with the number of bytes in the file or nil if the file
  doesn't exist

change_dir(path, &block)
- a boolen indicating if the current user is permitted to change to the
  requested path

dir_contents(path, &block)
- an array of the contents of the requested path or nil if the dir
  doesn't exist. Each entry in the array should be
  EM::FTPD::DirectoryItem-ish

delete_dir(path, &block)
- a boolean indicating if the directory was successfully deleted

delete_file(path, &block)
- a boolean indicating if path was successfully deleted

rename(from_path, to_path, &block)
- a boolean indicating if from_path was successfully renamed to to_path

make_dir(path, &block)
- a boolean indicating if path was successfully created as a new directory

get_file(path, &block)
- nil if the user isn't permitted to access that path
- an IOish (File, StringIO, IO, etc) object with data to send back to the
  client
- a string with the file data to send to the client
- an array of strings to join with the standard FTP line break and send to
  the client

The driver MUST have one of the following methods. Each method MUST accept a block and yield the appropriate value:

put_file(path, tmp_file_path, &block)
- an integer indicating the number of bytes received or False if there
  was an error

put_file_streamed(path, datasocket, &block)
- an integer indicating the number of bytes received or False if there
  was an error

Authors

James Healy james@yob.id.au http://www.yob.id.au John Nunemaker nunemaker@gmail.com Elijah Miller elijah.miller@gmail.com

Warning

FTP is an incredibly insecure protocol. Be careful about forcing users to authenticate with a username or password that are important.

License

This library is distributed under the terms of the MIT License. See the included file for more detail.

Contributing

All suggestions and patches welcome, preferably via a git repository I can pull from. If this library proves useful to you, please let me know.

Further Reading

There are a range of RFCs that together specify the FTP protocol. In chronological order, the more useful ones are:

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:

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"

For more information on EventMacine, a library that (among other things) simplifies writing applications that use sockets, check out their website.

Something went wrong with that request. Please try again.