.. _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*.