****************
* SAMPy MODULE *
****************

SAMPy is a Python implementation of the IVOA Simple Application
Messaging Protocol [1] version 1.2 (with Web Profile support).

SAMPy Python module (sampy.py) provides classes to easily:

1) instantiate one or multiple Hubs;
2) interface an application or script to a running Hub;
3) create and manage a SAMP client.

To have a complete API documentation, please follow the instructions
contained within the INSTALL file. The API documentation contains also 
a simple example of usage client side, which is similar to the client
test script distributed with this release (i.e. iclient.py, see also
client.py and all the examples under "examples" directory).


*********************
* SAMPy STAND-ALONE *
*********************

SAMPy package provides also a stand-alone program "sampy" capable to 
instantiate a persistent Hub. Here below the description of the
execution options as displayed by the help command:

shell > sampy -h


Usage: sampy [options]

Options:
  --version             show program's version number and exit
  -h, --help            show this help message and exit
  -k CODE, --secret=CODE
                        custom secret code.
  -d ADDR, --addr=ADDR  listening address (or IP).
  -p PORT, --port=PORT  listening port number.
  -f FILE, --lockfile=FILE
                        custom lockfile.
  -w, --web-profile     run the Hub enabling the Web Profile.

  Timeout group:
    Special options to setup hub and client timeouts.It contains a set of
    special options that allows to set up the Hub and clients inactivity
    timeouts, that is the Hub or client inactivity time interval after
    which the Hub shuts down or unregisters the client. Notification of
    samp.hub.disconnect MType is sent to the clients forcibly unregistered
    for timeout expiration.

    -t SECONDS, --timeout=SECONDS
                        set the Hub inactivity timeout in SECONDS. By default
                        it is set to 0, that is the Hub never expires.
    -c SECONDS, --client-timeout=SECONDS
                        set the client inactivity timeout in SECONDS. By
                        default it is set to 0, that is the client never
                        expires.

  Logging options:
    Additional options which allow to customize the logging output. By
    default SAMPy Hub uses the standard output and standard error devices
    to print out INFO level logging messages. Using the options here below
    it is possible to modify the logging level and also specify the output
    files where redirect the logging messages.

    -L LEVEL, --log-level=LEVEL
                        set the Hub instance log level (OFF, ERROR, WARNING,
                        INFO, DEBUG).
    -O FILE, --log-output=FILE
                        set the output file for INFO and DEBUG messages.
    -E FILE, --log-error=FILE
                        set the output file for WARNING and ERROR messages.

  Advanced group:
    Advanced options addressed to facilitate administrative tasks and
    allow new non-standard Hub behaviors. In particular the --label
    options is used to assign a value to hub.label token and is used to
    assign a name to the Hub instance. Option --auth-file sets the
    authentication file enabling the access control through Basic
    Authentication. The authentication file is a Berkeley DB file in Hash
    format containing a set of <user name>=md5(<password>)<group 1>,<group
    2>,<group 3>,... key=value pairs. Options --owner and --group are
    additional tokens (hub.owner.name and hub.owner.group respectively)
    available for possible administrative tasks and usable in conjunction
    with --restrict option for authentication tasks. --restrict option
    allows to restrict the Hub access only to OWNER or to a certain owner
    GROUP. Access restriction is actually enabled only if an
    authentication file is provided. --admin option defines the name of
    the administrator user in case of restricted access. The administrator
    user can always access the hub instance even if it is running with the
    OWNER restricion policy. The administrator must be declared in the
    authentication file. The very special --multi option allows to start a
    Hub in multi-instance mode. Multi-instance mode is a non-standard Hub
    behavior that enables multiple contemporaneous running Hubs. Multi-
    instance hubs place their non-standard lock-files within the <home
    directory>/.samp-1 directory naming them making use of the format:
    samp-hub-<PID>-<ID>, where PID is the Hub process ID while ID is an
    internal ID (integer).

    -l LABEL, --label=LABEL
                        assign a LABEL to the Hub.
    -o OWNER, --owner=OWNER
                        assign a OWNER to the Hub.
    -g GROUP, --group=GROUP
                        assign a GROUP to the Hub.
    -a FILE, --auth-file=FILE
                        filename for Basic Authentication.
    -r LEVEL, --restrict=LEVEL
                        set the access restriction to OWNER or GROUP.
    -A NAME, --admin=NAME
                        set the name of the administrator user.
    -m, --multi         run the Hub in multi-instance mode generating a
                        custom lockfile with a random name.

  SSL group:
    Additional options to launch the Hub instance using the Secure Sockets
    Layer (HTTPS). The --key-file and --cert-file parameters specify
    optional files which contain a certificate to be used to identify the
    local side of the connection. Often the private key is stored in the
    same file as the certificate; in this case, only the --cert-file
    parameter need be passed. If the private key is stored in a separate
    file, both parameters must be used. If the private key is stored in
    the certificate file, it should come before the first certificate in
    the certificate chain.

    -s, --https         run the Hub using the Secure Sockets Layer.
    -C FILE, --cert-file=FILE
                        set the certificate file.
    -K FILE, --key-file=FILE
                        set the key file. By default this option is ignored,
                        assuming that the private key is stored in the
                        certificate file.
    --cert-reqs=STRING  this option specifies whether a certificate is
                        required from the client side of the connection, and
                        whether it will be validated if provided. It must be
                        one of the three values NONE (certificates ignored,
                        default), OPTIONAL (not required, but validated if
                        provided), or REQUIRED (required and validated). If
                        the value of this option is not NONE, then the --ca-
                        certs option must point to a file of CA certificates.
    --ca-certs=FILE     the --ca-certs file contains a set of concatenated
                        "certification authority" certificates, which are used
                        to validate certificates passed from the client end of
                        the connection.
    --ssl-version=STRING
                        the --ssl-version option specifies which version of
                        the SSL protocol to use. Typically, the server chooses
                        a particular protocol version, and the client must
                        adapt to the server's choice. Most of the versions are
                        not interoperable with the other versions. If not
                        specified the default SSL version is SSLv23. This
                        version provides the most compatibility with other
                        versions client side. Other SSL protocol versions are:
                        SSLv2, SSLv3 and TLSv1.


************************
* BASIC AUTHENTICATION *
************************

If you intend to use the Basic Authentication feature, you might find
useful the utility script utils/sampasswd.py distributed with SAMPy. It
allows to easily create and manage an authentication file containing 
the users' passwords in SAMPy format, that is a Berkeley DB in hash
format where the key/value pairs are:

Keyword = <user name>
Value   = md5(<password>)<user group 1>,<user group 2>,...

Here below the list of options to drive the sampasswd.py script.

shell >./sampasswd.py -h

Options:
  --version             show program's version number and exit
  -h, --help            show this help message and exit
  -f FILE, --file-name=FILE
                        password file name (mandatory).
  -u USER, --user-name=USER
                        user's name.
  -g GROUP, --group-name=GROUP
                        user's group name or comma separated list of groups.

  Actions:
    Actions to be executed with the selected user and/or password file.

    -l, --list          list the users.
    -a, --add           add a new user.
    -d, --delete        delete the user.
    -c, --create        create password file if missing.


************************
* SECURE SOCKETS LAYER *
************************

SAMPy provides access to Transport Layer Security (often known as Secure
Sockets Layer) encryption and peer authentication facilities for
network sockets, both client-side and server-side. Within SAMPy context,
SSL should be used mainly to protect the communication with remote Hubs
which require Basic Authentication (otherwise Basic Authentication is 
considered an insecure password transmission system).

Therefore in the majority of the cases SSL communications with a
self-signed certificate provided server side is enough, but you can
need the clients providing their own certificates and validate them with
a set of Certification Authority certificates. Vice versa, the clients
might require a server certificate validation. All these special
cases, where a Certificate Authentication is required, are nominally
supported, but NEVER TESTED.

To learn how to create a certificate with OpenSSL [2] (usually
distributed with Linux) and self-sign it or prepare it in order to be
signed by a CA, you can read this tutorial:

  http://www.openssl.org/docs/HOWTO/certificates.txt


***********************************
* HTTP FILE SERVER UTILITY SCRIPT *
***********************************

Under utils directory, along with sampasswd.py utility script mentioned
above, there is http_file_server.py utility script. It is able to serve
a lockfile (or any other file) through an HTTP address. In the
following http_file_server.py options:

shell > ./http_file_server.py -h
Usage: http_file_server.py file [options]

Options:
  -h, --help            show this help message and exit
  -d ADDR, --addr=ADDR  listening address (or IP).
  -p PORT, --port=PORT  listening port number.

  

*******************************
* OTHER NON-STANDARD FEATURES *
*******************************

SAMPy automatically adds two extra keywords ("user" and "host") to the
messages sent using the Hub operations:

- samp.hub.notify
- samp.hub.notifyAll
- samp.hub.call
- samp.hub.callAll
- samp.hub.callAndWait

These extra keywords are directly taken at wire level from the XML-RPC
POST, exploiting the HTTP protocol features.


********************
* ACKNOWLEDGEMENTS *
********************

A special thanks to Mark Taylor [3] for his support during the SAMPy
debugging phase: a precious aid that has led SAMPy so far, fully
compliant with SAMP protocol and interoperable with JSAMP [4].


**********************
* CONTRIBUTIONS FROM *
**********************

- Douglas Burke
- Juan de Dios Santander Vela


**************
* REFERENCES *
**************

[1] http://www.ivoa.net/Documents/latest/SAMP.html
[2] http://www.openssl.org/
[3] http://www.star.bris.ac.uk/~mbt/
[4] http://deployer.astrogrid.org/software/jsamp/index.html

