Net-FTPSSL version 0.41 ======================= Net::FTPSSL is an object oriented Perl module which implements a simple FTPS client over a Secure Socket Layer (SSL) or Transport Layer Security (TLS) connection written following the directives described in RFC959 and RFC2228 INSTALLATION ===================================================================== To install this module type the following: perl Makefile.PL make make test make install NOTE: "make test" will prompt you to answer questions. But if you want to skip those questions and use their default answers, you can do "make test < /dev/null" and it will use all defaults. (make test < NULL for windows.) To install this module in an alternate location do: location=<install-location> perl Makefile.PL INSTALL_BASE=${location} make make test make install Then set PERL5LIB to "${location}/lib/perl5". DEPENDENCIES ===================================================================== This module requires these other modules and libraries: Net::SSLeay IO::Socket::SSL File::Basename Time::Local Sys::Hostname File::Copy IO::Socket::INET If you are going to have to tunnel through a proxy server, the following module is also required: Net::HTTPTunnel There are some more for running the test scripts as well. Test::More File::Spec SMOKE TESTERS ===================================================================== The test suite for this module honors your environment variable PERL_MM_USE_DEFAULT, and if it's set the test code just checks for syntax errors and missing dependancies. It skips over any interacive prompting and doesn't attempt to connect to a FTPS server. TESTING THE MODULE ===================================================================== As of v0.41, the test suite was 100% redesigned to be more modular to simplify testing out this module. The original test suite was just getting more and more messy, making it difficult to test everything properly or even follow what the tests were actually doing. So bear with me as I work out he kinks in this new testing process. When you run "make test" it only prompts for your input once and then remembers your answers to use for all other test programs. It then tries to auto-detect certain "common" issues that need work arrounds. And should you rerun "make test" again, it remembers your answers from last time and gives them back as default answers for the current run. See the next to last section for them main list of questions asked and their meanings. If you can't connect to a server, it doesn't necessarily mean that this module isn't working. Most likely the server you are testing against requires additional SSL options before it will accept any connections from the client. That the assumptions made by these test programs may just not match your FTPS server's configuration. The most common reasons for failure is that your FTPS server requires a FTPS client to use specific SSL options that are not turned on by default by the test cases. These missing SSL options could prevent you from connecting to a FTPS server or prevent you from creating a data channel for transfering data with the FTPS server. If you think that this is the reason, see "perldoc IO::Socket::SSL" to review what SSL options are available. Or "perldoc Net::FTPSSL" for options specific to my module. I'll cover how to insert those extra options into the mix later on by hacking a single config file that is automatically generated. If you are able to log in to run the test cases, they may silently add some additional options based on known server issues encountered in the past. But if it's not a known issue, you may have to open a CPAN ticket with me to figure out whats wrong. WHY DOESN'T "make test" RUN ALL THE t/*.t TESTS? ===================================================================== Normally all test are run. But there are cases when it stops early. The early tests validate if the answers you gave at the prompts are usable. If it encounters issues using them, it will stop running the test cases once it decides it can't use your answers to configure the test programs to talk to your FTPS server. Since without connectivity, all future tests would fail. So why run them and hide the root cause of the failure? That would just make troubleshooting that much more difficult. WHY DO THE TEST CASES ASK THE SAME QUESTIONS OVER AND OVER AGAIN. ===================================================================== When running 'make test', it should only ask the questions while running test 't/02-ask-questions.t'. All the other test cases should remember what you answered for this test. So if the questioning is reapeated, there is a bug in how I detect if 'make test' is running. So please open a CPAN ticket and atach log t/logs/02-ask-questions.log.txt and I'll figure out what's wrong. Different platforms work differently and this log will help me figure out what the proper test for your OS & perl vendor is. If you are running the individual tests manually via "perl t/test-case.t" then it's working as intended. Each test case will prompt you for the answers it needs. THE CONFIG FILE -- MANUALLY ADDING EXTRA OPTIONS: ===================================================================== If after answering all the questions and your research shows you that your server requires you to add an additional specific option in order to work, you may do so by editing the following file: t/test-helper/ftpssl.cfg Add to the end of the file in the option using the following format: EXTRA_<option>=<value> Then that <option> will be used during the test cases the next time you run "make test". Feel free to add more options if needed. Once you get things working, consider opening a CPAN ticket so that I can figure out a way to automate the check. Either by adding another question or adding additional test cases to the mix. WARNING: Any usernames & passwords stored in this config file are not encrypted. They are stored in clear text in this config file! LOG FILES ===================================================================== Most test cases generate log files showing the interaction between the FTPS server and the client. These log files can be found under: t/logs/*.log.txt The log files generated are named after the test cases. If a test case generates multiple log files, then they are variants on the name. TROUBLESHOOTING ===================================================================== While support is very limited, a copy of the log file showing the problem generated by the tests would be needed to help analyze what went wrong with talking to your particular FTPS server. I'll also need the config file generated to see how you answered the questions. If all the tests passed and it's your code thats failing you'll need to provide me a small sample program demonstrating the problem and the log file that goes with it. You can turn on the logs with the following command options. $ftpssl = Net::FTPSSL->new(server, ..., Debug => 1, DebugLogFile => "myLog.txt", Croak => 1); Then call: $ftpssl->trapWarn(); This is so that any warnings generated will also show up in the log file. This will provide context to any warnings. Just be aware that a particular FTPS command may fail if your FTPS server doesn't support that command or if your login doesn't have enough permissions to perform the desired command on the FTPS server. If you are submitting a patch for consideration, please also provide the above trace file in case I can't duplicate the issue against the FTPS servers I have available to me for testing. For new functionality, it may help if you could temporarily grant me a login that I can test against. Otherwise I may ask your help in beta testing new code. My servers can't always support all possible configurations or behaviours. If you're going to set up temporary access for testing, use my CPAN mailing address to give me the details so that this information won't show up in the ticket where it can't be deleted. [cleach@cpan.org] It's unlikely I'll respond to email requests not associated with a CPAN ticket. So put "CPAN BUG ID ..." in the subject line so that I don't delete it unread. I get too much spam as it is to otherwise read everything. TEST t/26-ccc_test.t FAILS ===================================================================== The CCC command is very unstable on some servers. Sometimes it works and sometimes it fails. The issue seems to be on the server side when it unexpectedly closes the command channel afterwards. ADVANCED TROUBLESHOOTING ===================================================================== Sometimes the logs to Net::FTPSSL are just not enough. Sometimes it would be very helpful to see the IO::Socket::SSL trace as well. The logging can be turned on statically or dynamically. But the easiest way for submitting a CPAN ticket is statically as shown in the 1st example: use IO::Socket::SSL qw (debug3): # Turns on verbose SSL loging. use Net::FTPSSL; # The STDERR hack open (STDERR, "> myLogfile.txt"); # Redirects STDERR to this file. $ftps = Net::FTPSSL->new ($server, ..., Debug=>1); $ftps->trapWarn (); ... This will mix writting the SSL trace & FTPSSL logs together to STDERR which is also redirected to the requested file. Providing more inforamtion on what is happening with the connection to the server. Just don't write to STDERR yourself in your test program! It will confuse the log generated. But if you prefer, and you have a new enough version of IO-Socket-SSL, you can also toggle it at any time by setting: $IO::Socket::SSL::DEBUG = 3; # Turn on Full Logging to STDERR. or $IO::Socket::SSL::DEBUG = 0; # Turn logging off again! Too bad there seems to be no way to redirect the SSL logs to a file of your choice without the above hack. You can also dynamically do this via: $Net::SSLeay::trace = 4; # Turn on Full Logging to STDERR as Warnings. or $Net::SSLeay::trace = 0; # Turn logging off again! The good news about SSLeay is that anything it writes out is done as a warning. So Net::FTPSSL can trap those debug statements. So if I can ever figure out a way to redirect the SSL logs to a file without the above STDERR hack, I'll implement a dynamic solution as an option to new(). So suggestions are welcome! ===================================================================== Here are the main questions asked: (A question may be skipped over if a previous answer makes a question meaningless.) ===================================================================== 1) Do you want to run the server connectivity tests ? (Y|N) [N] If you don't have a FPTS server to test against, answer "N", and you won't be asked any more questions. Answering "Y" means you wish to run tests against your FTPS server and you will be asked more questions. 2) Are we restricted to read-only tests ? (Y|N) [N] N - It will run the entire test suite. Y - It will skip all tests that updates the contents of the FTPS server. 3) Server address ( host[:port] ) ? [] As you can see, the 1st time run there is no default. But once you provide one, the next time you run the test it will remember your answer. myserver - Connects to server "myserver" using the default port. myserver:33 - Connect to "myserver" using port 33. 4) User ? [anonymous] Gives you the chance to enter the user name to use when connecting to your FTPS server. 5) Password [a space for no password] ? [user@localhost] Gives you a chance to enter the password that goes with your username. WARNING: It echos your password in clear text. So make sure no one is looking over your shoulder when you enter this. 6) Directory ? [<HOME>] The default is the home directory you are in when you initially log into your server. It's asking for a directory that the test program can upload files to and delete files from as well as other tasks. For best results, when the tests are being run, nothing else should be working with files inside that directory. 7) Connection mode (I)mplicit, (E)xplicit, or (C)lear. ? (I|E|C) [E] Choose the type of connection you wish to have. 8) Data Connection mode (C)lear or (P)rotected. ? (C|S|E|P) [P] When transfering date back & forth between your FTPS server do you wish your data to be sent in clear text? Or protected by encryption. The S & E options are not currently supported. 9) What encryption protocal to use ? (SSLv23|TLSv1|TLSV11|TLSv12) [TLSv12] Case is important here, the default is the most secure protocall. But I allow the others since not all FTPS servers support all protocalls. The new TLSv13 will show up in the list only if your installed version of Net::SSLeay and IO::Socket::SSL both support it. 10) Use (P)ASV or (E)PSV for data connections ? (P|E) [P] I recommend using the default answer here. 11) Will you be FTP'ing through a proxy server ? (Y|N) [N] If you answer Y, it will use module "Net::HTTPTunnel" for this purpose. If this optional module isn't installed, you won't see this question. --) I'm not showing the questions for tunneling should you answer Y. 12) Will you be using Client Certificates ? (Y|N) [N] You can answer yes and it will ask you further questions about your certificates. But if the FTPS server doesn't ask you for the credentials, the certificates won't be used. --) I'm not showing the questions for certificates should you answer Y. Hopefully they should be obvious to answer based on my comments above. 13) Should we keep automatically-added extra Net::FTPSSL options from previous test runs ? (Y|N) [Y] The only time you should answer "N" to this question is if you changed which FTPS server the test cases are running against. Usually you should answer "Y" to this question! Just remember if you rerun the tests again at a later date, it will remember your answers from last time and use them as the new defaults! But question 13 will always default to "Y". COPYRIGHT AND LICENCE ===================================================================== Copyright (C) 2005 by Marco Dalla Stella Copyright (C) 2009 - 2018 by Curtis Leach [cleach@cpan.org] This library is free software; you can redistribute it and/or modify it under the same terms as Perl itself, either Perl version 5.8.6 or, at your option, any later version of Perl 5 you may have available.