.. _usage:

Usage
=====

Django Conntrackt provides a very simple interface for reading the information
about network connections across projects, as well as for obtaining *iptables*
rules.

The Conntrackt content is currently being added through Django's administration
interface.

Conntrackt key concepts
-----------------------

There is a couple of key concepts to be aware of throughout the documentation:

Project
    A project is used to group the related entities. Project usually maps to
    business projects being worked on by the organisation members.

Location
    Location is used to group the related entities within a project. Locations
    can be abstract, like *primary site*, *secondary site*, or *disaster
    site*. They can also be more specific, like *Belgrade*, or *Stockholm*. The
    layout of locations that you choose is completely up ot you.

Entity
    Entity is an origin or destination of network communication. An entity can
    represent a single physical or virtual device (server, router, or some other
    network-capable device), or it can represent a subnet (therefore being
    mapped to multiple physical or virtual devices).

    Every entity must have an assigned project and location.

Interface
    Interface is used for representing a specific network interface on an
    entity. In regular case, where the entity is a physical or virtual device,
    an interface will map to a single IP address.

    An interface is also used to provide subnet information for entities that
    represent subnets.

    Multiple interfaces can be assigned to an entity as well.

Communication
    Communication is used to specify the planned connections between
    entities. This information is useful for keeping track which entity is
    talking to which entity (and using which interfaces), allowing easier
    tracking of what's happening in the project.

    In addition, this information can be used to generate the iptables rules for
    servers to restrict the access.

Navigating through Conntrackt
-----------------------------

Conntrackt tries to employ a simple and lean web interface for all of its
tasks. Every Conntrackt page has a navigation bar at the top, that lets you
access the most common pages in the application.

The *Main Page* links will take you to the homepage of Conntrackt. If you want
to add data to conntrackt, click on the *Administration* link, which will take
you to Django's built-in administration interface.

If you are not logged-in, you can click on the *Log-in* link that will take you
to the log-in page where you can provide your credentials (username and
password). In case you are already- logged-in, you will instead see your
*username* and *log-out* link.

Homepage
~~~~~~~~

This page provides an overview of projects and entities belonging to the
projects. No information will be shown if there are no projects defined.

Each project's information is shown in a small frame on the page, with project
name at the top, and listing of entities belonging to the project under it.

Clickin on the project name will take you to project details page, while
clicking on an entity name will take you to entity details page.

In addition, small clickable icons are show next to the project and
entities. Clicking on the book-like icon next to a project will trigger download
of ZIP archive that contains *iptables* rules for all of the project's entities
in separate files. This is a convenient way to obtain all of the *iptables* for
a project.

If you click on the icon next to an entity, you will be instead offered to
download *iptables* rules for that specific entity in plain-text format.

Project details page
~~~~~~~~~~~~~~~~~~~~

The project details page provides an overview of project's locations, with
entities listed under the location to which they belong to.

Each location is contained inside of a small frame, with location name at the
top, and listing of entities in the location below it.

Clicking on an entity name will take you to entity details page.

In addition, small clickable icons are show next to the location and
entities. Clicking on the book-like icon next to a location will trigger download
of ZIP archive that contains *iptables* rules for all of the location's entities
in separate files. This is a convenient way to obtain all of the *iptables* for
a specific location in a project.

If you click on the icon next to an entity, you will be instead offered to
download *iptables* rules for that specific entity in plain-text format.

Entity details page
~~~~~~~~~~~~~~~~~~~

This page provides more details about an entity in a project. You will be
presented with the following information on this page:

* Entity's project name.
* Entity's location name.
* Informationg about incoming and outgoing communications.
* Inline iptables rules.

The project name is clickable, and it will take you to project details page.

The information about incoming communications shows all communications that have
one of this entity's interfaces as destination. The listing will show an IP
address/subnet of the source, protocol used in communication, and port number
(if applicable).

Similarly, the outgoing communications listing will display communications where
the entity is the source (starting point), and includes information about
destination IP address/subnet, protocol user in communication, and port number
(if applicable).

The iptables listing can be obtained either by copy/pasting it from the page, or
by clicking on the *Download* button below it (which will generate a plaintext
file containing the same iptables rules as listed in the *iptables rules*
frame).


Managing data
-------------

Data for Conntrackt can be added and modified using Django's built-in
administration GUI. You can easily access the administration GUI from
Conntrackt's pages, by clicking on the *Administration* link in the navigation
bar.

From there you can add new projects, locations, interfaces, entities, and
communications. You can also click on links towards them to get a full listing
from where you can modify existing entries.

The admin interface for Conntrackt behaves the same as for every Django
application, except for some convenience functionality that helps speed-up
adding or modification of some data.

The interfaces, entities, and communications pages allow editing most of the
data inline, which can speed-up the process quite a bit. In addition, all three
pages provide filters that allow you to easily view data specific to a
particular project and/or location. The filters are available on the right
side.

Although interfaces can be managed separately, you may find it much easier to
manage them from within the entity pages. When adding or modifying an entity,
you will have some inline forms for specifying entity's interfaces. This is the
recommended way to add and modify the interfaces for entities.

Projects
~~~~~~~~

For every project you can provide the following information:

* *Name* of a project.
* *Description* of a project.

Locations
~~~~~~~~~

For every location you can provide the following information:

* *Name* of a location.
* *Description* of a location.

Entities
~~~~~~~~

For every entity you can provide the following information:

* *Name* of an entity.
* *Description* of an entity.
* *Project* to which the entity belongs.
* *Location* at which the entity is available.

In addtion, you can easily add and modify the interfaces of an entity through an
inline form.

On an entity listing page you can also reassign the entities easily to different
locations and/or projects using the inline fields.

Managing interfaces data
~~~~~~~~~~~~~~~~~~~~~~~~

For every interface you can provide the following information:

* *Name* of an interface. This should usually by system-specific name, for example *eth0*.
* *Description* of an interface.
* *Entity* to which an interface belongs.
* *Address* of an interface. This is usually an IP address.
* *Netmask* of an interface. When specifying a single specific IP address, this
  should be set to 255.255.255.255 (the default).

When an interface is representing a single IP address, the *address* should be
set to interface's IP address, and *netmask* should be set to
*255.255.255.255*. If specifying the subnet, the *address* and *netmask* will be
used to denote the subnet of format *address*/*netmask*. Conntrackt
distinguishes between these two types of *address* and *netmask* combination,
and produces appropriate iptables rules in both cases.

In addition to specifying an interface from the dedicated interface pages, a
more convenient way to add them is when adding or modifying the end
entities. Each end entity will have inline forms where you can provide the
information about its interfaces.

Another useful way to modify the interface information is using the inline
fields on the interface listing page (especially when making changes to a large
number of entities due to subnet changes for the in the project).

Managing communications data
~~~~~~~~~~~~~~~~~~~~~~~~~~~~

For every communication you can provide the following information:

* *Source* of communication, which denotes a specific interface (of a specific
  entity) **from** which the communication is established.
* *Destination* of communication, which denotes a specific interface (of a
  specific entity) **to** which the communication is established.
* *Protocol* used for the communication. Supported protocols currently include
  *TCP*, *UDP*, and *ICMP*.
* *Port* used for the communication. In case of *TCP* and *UDP*, this value
  denotes the actual port, while in case of *ICMP* protocol, this value will
  denote the **ICMP package type** - specified as **numeric** value.

When editing communications you may find it particularly useful to add them
through the communications list page by first specifying a filter (by project
and/or location), and then clicking on the *Add communication* link. This way
the filter will be applied to *source* and *destination* fields.

For example, if you choose project **Test**, and location **Main site**, and then click
on the *Add communication* button, the *source* and *destination* fields will be
limited to entity interfaces that specificaly belong to the **Test** project and
location **Main site**.

You can also easily modify existing communications using the communication
listing page. From there you can easily modify source, destination, protocol,
and port. Similarly to adding a new communication, you can apply a filter that
will narrow-down the selection for source and destination. It is highly
recommended to apply the filter in this way.

Iptables generation
-------------------

In addition to tracking the communications across a project, one of the main
features of Conntrackt is its ability to generate the *iptables* rules for all
entities in project based on provided communications data.

These *iptables* rules can then be easily applied to *GNU/Linux* entities. The
rules are generated with the following rules in mind:

* Default target for *INPUT* chain is *DROP*.
* Default target for *FORWARD* chain is *DROP*.
* Default target for *OUTPUT* chain is *ALLOW*.
* No limits are imposed on the *OUTPUT* chain.
* Rules for the *INPUT* chain are applied using a whitelist basis. Only
  explicitly defined communications in the iptables will be used to generate the
  *ACCEPT* rules. The matching is performed based on *source*, *protocol*, and
  destination *port*.