======================================================================
ECMWF-ECaccess version 6.3.1
======================================================================

This package provide Perl scripts for the management of files, file
transfers, jobs, ectrans associations and events at ECMWF. They can
be run by any user and on any Member State host. They use the perl
library ECMWF::ECaccess which give access to the ECMWF ECaccess Web
Services (or ECaccess API).

Running these commands requires a valid certificate. Certificates can
be created with the "ecaccess-certificate-create" command from an ECMWF
user identifier and a PASSCODE (using a security token), it generates a
certificate in ".eccert.crt" in the user's home directory.

You need to ensure the following environment variables are set with
the correct values:

http_ecaccess=gateway.meteo.ms:9080
https_ecaccess=gateway.meteo.ms:9443

(e.g. if your local ECaccess Gateway name is "gateway.meteo.ms" and
you are using the default ECaccess http/s ports 9080/9443)

If you don't define these variables then the default behaviour is to
use the boaccess.ecmwf.int server at ECMWF.

1) INSTALLATION ON UNIX OR MAC-OS-X
2) INSTALLATION ON WINDOWS
3) TEST FAILURE
4) WHAT YOU GET
5) CREATE PACKAGE FOR DISTRIBUTION
6) COPYRIGHT AND LICENCE

======================================================================
1) INSTALLATION ON UNIX OR MAC-OS-X
======================================================================

A) IF YOU DON'T HAVE ROOT ACCESS
--------------------------------

First load the latest release of the local-lib package which can be
found at the following place:

http://search.cpan.org/dist/local-lib

Save the archive in one directory and then from this directory issue
the following commands:

   gunzip local-lib-<VERSION>.tar.gz
   tar -xf local-lib-<VERSION>.tar
   cd local-lib-<VERSION>
   perl Makefile.PL --bootstrap

If you have questions that you don't understand just press the Enter
key to accept the default values.

   make
   make test
   make install

Now you can run the following command:

   perl -I$HOME/perl5/lib/perl5 -Mlocal::lib

This will give you a list of environment parameters to configure in
your startupt script (e.g. ~/.bashrc or ~/.cshrc). Logout and login
again to get your new environment parameters.

Then do the following:

   perl -MCPAN -eshell
   cpan[1]> o conf init connect_to_internet_ok urllist
   cpan[1]> o conf commit
   cpan[1]> quit

Answer yes if prompted the following:

"If no urllist has been chosen yet, would you prefer CPAN.pm to connect
to the built-in default sites without asking? (yes/no)?"

Then answer to the best of your knowledge.

You can now skip the following paragraph and go directly to C).

B) IF YOU HAVE ROOT ACCESS
--------------------------

Login as <root> and go to C).

C) INSTALLATION
---------------

Please before starting the installation make sure you have OpenSSL
installed. More information at the following place:

   http://www.openssl.org

(On Debian systems, you will need to install the libssl-dev package, at
least for the duration of the build. It may be removed afterwards)

To start the installation of the Webtoolkit, type the following commands
to make sure the required Perl Modules are installed (Can't locate object
method "install" errors while running these commands should be ignored):

   perl -MCPAN -e "install Class::Inspector"
   perl -MCPAN -e "install Getopt::Long"
   perl -MCPAN -e "install Pod::Usage"
   perl -MCPAN -e "install Net::HTTP"
   perl -MCPAN -e "install URI::Escape"
   perl -MCPAN -e "install Term::ReadKey"
   perl -MCPAN -e "install Term::ProgressBar"
   perl -MCPAN -e "install Term::Prompt"
   perl -MCPAN -e "install Number::Bytes::Human"
   perl -MCPAN -e "install MIME::Base64"
   perl -MCPAN -e "install IO::Socket::INET6"
   perl -MCPAN -e "install IO::Socket::SSL"
   perl -MCPAN -e "install SOAP::Lite"

Then in order to install the ECMWF::ECaccess module, go to the
ECMWF-ECaccess directory and type the following:

   perl Makefile.PL
   make
   make test
   make install

======================================================================
2) INSTALLATION ON WINDOWS
======================================================================

Install either the StrawberryPerl or the ActivePerl software from the
following place:

http://strawberryperl.com
http://www.activestate.com

Then from a Windows Console (Cmd) issue the following
commands:

   perl -MCPAN -e "install Class::Inspector"
   perl -MCPAN -e "install Getopt::Long"
   perl -MCPAN -e "install Pod::Usage"
   perl -MCPAN -e "install Net::HTTP"
   perl -MCPAN -e "install URI::Escape"
   perl -MCPAN -e "install Term::ReadKey"
   perl -MCPAN -e "install Term::Prompt"
   perl -MCPAN -e "install Number::Bytes::Human"
   perl -MCPAN -e "install MIME::Base64"
   perl -MCPAN -e "install Crypt::SSLeay"
   perl -MCPAN -e "install IO::Socket::INET6"
   perl -MCPAN -e "install IO::Socket::SSL"
   perl -MCPAN -e "install SOAP::Lite"

Then from the ECMWF install directory:

   perl Makefile.PL
   dmake
   dmake test
   dmake install

Please note the "Term::ProgressBar" Module is not available on Windows,
therefore the "-progress" option of the ecaccess-file-get/mget and
ecaccess-file-put/mput commands can not be used.

======================================================================
4) TEST FAILURE
======================================================================

Please note that if your module fails some of its tests you can get more output
from the test routines by running:

   make TEST_VERBOSE=1 test

(for Windows replace make by dmake)

If you have any problem installing the ECMWF::ECaccess Module then please check 
the ECaccess pages at the following place:

   https://confluence.ecmwf.int/x/pw_YAg

Or contact us at servicedesk@ecmwf.int.

======================================================================
5) WHAT YOU GET
======================================================================

After installation the following commands are available:

Certificate Management:

 - ecaccess-certificate-create
 - ecaccess-certificate-list

General Information:

 - ecaccess-cosinfo

Gateway Management:

 - ecaccess-gateway-connected
 - ecaccess-gateway-list
 - ecaccess-gateway-name

Association Management:

 - ecaccess-association-delete
 - ecaccess-association-get
 - ecaccess-association-list
 - ecaccess-association-protocol
 - ecaccess-association-put

ECtrans Management:

 - ecaccess-ectrans-delete
 - ecaccess-ectrans-list
 - ecaccess-ectrans-request
 - ecaccess-ectrans-restart

Event Management:

 - ecaccess-event-clear
 - ecaccess-event-create
 - ecaccess-event-delete
 - ecaccess-event-grant
 - ecaccess-event-list
 - ecaccess-event-send

File Management:

 - ecaccess-file-chmod
 - ecaccess-file-copy
 - ecaccess-file-delete
 - ecaccess-file-dir
 - ecaccess-file-get
 - ecaccess-file-mdelete
 - ecaccess-file-mget
 - ecaccess-file-mkdir
 - ecaccess-file-modtime
 - ecaccess-file-move
 - ecaccess-file-mput
 - ecaccess-file-put
 - ecaccess-file-rmdir
 - ecaccess-file-size

Job Management:

 - ecaccess-job-delete
 - ecaccess-job-get
 - ecaccess-job-list
 - ecaccess-job-restart
 - ecaccess-job-submit

Queue Management:

 - ecaccess-queue-list

For each command the "-help" option will give you a brief help message and
the "-man" option will give you the full documentation. In case of problem
you can also use the "-debug" option which will force a dump of the protocol
exchanges with your ECaccess Gateway.

======================================================================
5) CREATE PACKAGE FOR DISTRIBUTION
======================================================================

If you want to create a binary package of your distribution (e.g. for
ease of deployement) then you can use the "Makedistrib" script.

The required libraries to run this script are the following:

   perl -MCPAN -e "install PAR"
   perl -MCPAN -e "install PAR::Packer"
   perl -MCPAN -e "install Archive::Tar"

This will create a compressed file which can be distributed to your
users:

  ecaccess-webtoolkit-bin-6.3.1-<OS>.tar.gz

======================================================================
6) COPYRIGHT AND LICENCE
======================================================================

Copyright (C) 2022 by ECMWF (Laurent.Gougeon@ecmwf.int)

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.8 or,
at your option, any later version of Perl 5 you may have available.