README
¶
Go FTP Secure server with support for local file system and Microsoft Azure Blob storage
A pure go FTP Secure server with support for local file system and Microsoft Azure Blob storage.
The interface based file system makes easy to support different file systems. Please tell me if you are interested in something not covered here.
Features
This server implements most - not all - the FTP commands available. This should be enough for most passive clients, below you will find a tested program list.
The main features are:
- Local file system support (ie standard FTP)
- Azure blob storage backed file system
- Unsecure (plain) FTP
- FTP Secure explicit
- FTP Secure implicit
- File system agnostic
- Azure nested directory support (thanks to Shuichiro MAKIGAKI)
- Pluggable logging system (thanks to logrus)
Implemented commands
| Command | Since version |
|---|---|
| USER | 1.0 |
| PASS | 1.0 |
| PWD | 1.0 |
| TYPE | 1.0 |
| PASV | 1.0 |
| EPSV | 1.0 |
| LIST | 1.0 |
| SYST | 1.0 |
| CWD | 1.0 |
| CDUP | 1.0 |
| SIZE | 1.0 |
| RETR | 1.0 |
| STOR | 1.0 |
| DELE | 1.0 |
| FEAT | 1.0 |
| QUIT | 1.0 |
| NOOP | 1.0 |
| MKD | 1.0 |
| RMD | 1.0 |
| REST | 1.0 |
| AUTH | 1.0 |
| PROT | 1.0 |
| NLST | 1.1 |
| LIST nested | 1.1 |
| CWD nested | 1.1 |
| MKD nested | 1.1 |
This list may not be updated: please refer to session.go source file to the updated list.
How to build
The main FTP server object can be called on its own in your project. Here, however, I give you a very simple program to test it. In order to use it download it, compile it and launch it. Here we suppose you have installed GO on your build machine and have the GOPATH environment variable set.
Download
With this command you can download the code with all its references. You can also use it later to update to the latest source code:
go get -u github.com/mindflavor/ftpserver2
Build
To build the application use this code. The binary will be saved in the %GOPATH\bin folder ($GOPATH in linux):
go install github.com/mindflavor/ftpserver2
Use
Here we assume you have a folder called ftphome in your C:\ disk. Substitute it with your FTP home folder.
Windows
%GOPATH%\bin\ftpserver2 -lfs C:\ftphome
Linux
Here we assume you have a folder called /mnt/ftphome on your file system. Substitute it with your FTP home folder.
sudo $GOPATH%/bin/ftpserver2 -lfs /mnt/ftphome
You need to be su in order to listen on port 21 (standard FTP command port). If you use another port you can start the program without sudo. Check the parameters section for how to do it.
Azure blob storage
In order to have the FTP server serve the azure storage blobs simply replace the -lfs parameter with -ak and -an like this:
$GOPATH/bin/ftpserver2 -ak <mystorageaccount> -as <shared_key_primary_or_secondary>
More info on the parameters in the Parameters section.
Some screenshots
This is an example of execution in ubuntu:
As you can see here, TLS is available (it's up to you to use valid certs however):
Here is how an Azure storage account appears in Chrome:
Parameters
At any time you can call the executable with -help flag in order to be reminded of the parameters.
| Flag | Type | Description | Default |
|---|---|---|---|
an |
string | Azure blob storage account name (1) | nil |
ak |
string | Azure blob storage account key (either primary or secondary) (1) | nil |
crt |
string | TLS certificate file (2) | nil |
key |
string | TLS certificate key file (2) | nil |
lDebug |
string | Debug level log file | nil |
lError |
string | Error level log file | nil |
lInfo |
string | Info level log file | nil |
lWarn |
string | Warn level log file | nil |
lfs |
string | Local file system root (3) | nil |
ll |
string | Minimum log level. Available values are Debug, Info, Warn, Error |
Info |
maxPasvPort |
int | Higher passive port range | 50100 |
minPasvPort |
int | Lower passive port range | 50000 |
plainPort |
int | Plain FTP port (unencrypted). If you specify a TLS certificate and key encryption you can pass -1 to start a SFTP implicit server only | 21 |
tlsPort |
int | Encrypted FTP port. If you do not specify a TLS certificate this port is ignored. If you specify -1 the implicit SFTP is disabled | 990 |
Notes
1.These two flags must be specified together. If you need to retrieve the storage account key look here http://stackoverflow.com/questions/6985921/where-can-i-find-my-azure-account-name-and-account-key. You cannot both specify this flags and the local file system one (lfs).
2.These two flags must be specified together. Without either one the secure extensions of FTP will be disabled. This article (http://stackoverflow.com/questions/12871565/how-to-create-pem-files-for-https-web-server) explains how to generate both the certificate file and the key one.
3.You cannot both specify this flag and the azure storage ones (an and ak).
ToDo
- Better tests. Coverage is abysmal. Script unit testing for a distributed state machine such as FTP is a PITA though.
- File access privilege check (right now is ignored).
- Authentication. Right now the FTPServer delegates authentication to the caller but the provided executable does not validate the passed identity.
Tested clients
PC
Android
License
Please refer here: LICENSE.
Contributing
If you want to contribute please do so, just fork and ask for merge. An huge thank you to everyone contributing (please see here the GitHub contributors page for their names).
Documentation
¶
Overview ¶
Package main is the sample application. Windows users should be aware that the Windows firewall might block the socket creation. To avoid this, insert the executable in the exclusion list
Source Files
Directories
¶
| Path | Synopsis |
|---|---|
|
Package ftp handles the ftp server main class.
|
Package ftp handles the ftp server main class. |
|
datachannel
Package datachannel handles the data sink between the FTP Server and the client
|
Package datachannel handles the data sink between the FTP Server and the client |
|
fs
Package fs exposes the required interface needed by the FTP Server in order to use the fs as backend file system
|
Package fs exposes the required interface needed by the FTP Server in order to use the fs as backend file system |
|
fs/azure
Package azureFS implements fs.FileProvider and handles Azure blob storage
|
Package azureFS implements fs.FileProvider and handles Azure blob storage |
|
fs/azure/azureBlob
Package azureBlob implements the fs interfaces for the local file system
|
Package azureBlob implements the fs interfaces for the local file system |
|
fs/azure/azureContainer
Package azureContainer implements fs.File but is specific for Azure containers
|
Package azureContainer implements fs.File but is specific for Azure containers |
|
fs/localFS
Package localFS implements the fs interfaces for the local file system
|
Package localFS implements the fs interfaces for the local file system |
|
fs/localFS/physicalFile
Package physicalFile implements the fs interfaces for the local file system
|
Package physicalFile implements the fs interfaces for the local file system |
|
portassigner
Package portassigner implements a thread safe port assigner in a predefined range
|
Package portassigner implements a thread safe port assigner in a predefined range |
|
session
Package session handles the FTP session state
|
Package session handles the FTP session state |
|
session/securableConn
Package securableConn hides the difference between a plain text connection and an encrypted one so there is no need to track the difference from outside.
|
Package securableConn hides the difference between a plain text connection and an encrypted one so there is no need to track the difference from outside. |
|
Package identity exposes the Identity interface
|
Package identity exposes the Identity interface |
|
basic
Package basicidentity implements the identity.Identity interface for basic (ie delegated) identity authentication.
|
Package basicidentity implements the identity.Identity interface for basic (ie delegated) identity authentication. |