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.

