=============
Documentation
=============

Components
==========

The IPA suite consists of the following components:

* ``ipa-sql``, a database schema for PostgreSQL 9.0 or later 
  *(required install)*

  The ``sql/`` directory contains a database schema for PostgreSQL 9.0 or
  later.  Please refer to `sql/README`_ for more detailed information about the
  schema, as well as instructions on setting up the IPA database.

.. _`sql/README`: sql.html

* ``libipa``, a C library for IPA data access
  *(required install)*

  libipa is a shared library that provides an application programming interface
  to data stored in IPA.  libipa is documented in the `include/ipa/ipa.h`_
  header file.

.. _`include/ipa/ipa.h`: libipa/index.html

* ``ipa-utils``, command-line utilities for managing and querying IPA data
  *(required install)*

  See `utils/README`_ for documentation on these utilities.

.. _`utils/README`: utils.html

* ``ipa-python``, a Python module for IPA data access
  *(optional install)*

  ipa-python allows Python applications to import, export, and query IPA
  data. Details of the ipa-python interface are available in
  `python/lib/ipa/__init__.py`_

.. _`python/lib/ipa/__init__.py`: python/index.html

* ``Cascade``, a web front-end for querying and managing IPA data
  *(optional install)*

  IPA/Cascade is a web application designed to simplify the process of querying
  and managing IPA data.  Please refer to `cascade/README`_ for more detailed
  information about the IPA/Cascade application.

.. _`cascade/README`: cascade.html

The following diagram shows how these components interact with each other, and
with external applications and utilities.  Components bundled in the IPA
distribution are shown in red.

.. image:: images/ipa_system_diagram.png

Requirements
------------

The IPA database schema requires PostgreSQL 9.0 or later.

``libipa`` requires the PostgreSQL client library (``libpq``), version 9.0 or
later.

``libipa`` requires ``glib`` 2.6 or later, available at http://www.gtk.org.

``ipa-python`` requires the netsa-python_ support module (version 1.3 or
greater) for database access.

.. _netsa-python: http://tools.netsa.cert.org/netsa-python/index.html

``Cascade`` requirements are detailed in `cascade/README`_.


Installation
============

The recommended sequence for installing IPA from source is:

1.  Load the database schema as per `sql/README`_.

2.  Run the top-level ``./configure`` script, followed by ``make`` and ``make
    install``, the latter of which may require superuser privileges.
    
    1. The ``./configure`` script, in addition to building libipa and the IPA
       command-line utilities, will try to find a Python interpreter and
       other dependent packages for ipa-python.

    2. If these dependencies are available, ``ipa-python`` will automatically
       be built and installed unless you supply the ``--without-python``
       argument to the configure script.

3.  Optionally, install and configure the IPA/Cascade web application as per
    `cascade/README`_.

License
=======

* GNU General Public License (GPL) Rights pursuant to Version 2, June 1991
* Government Purpose License Rights (GPLR) pursuant to DFARS 252.225-7013


Support
=======

For help with IPA installation/usage, or to submit a bug report, send email to
netsa-help@cert.org
