diff --git a/docs/quickstart.rst b/docs/quickstart.rst --- a/docs/quickstart.rst +++ b/docs/quickstart.rst @@ -1,4 +1,4 @@ -Quick-start Guide +Quick-start guide ================= This chapter provides quick-start instructions in order to allow you to quickly deploy and test Django Conntrackt application. diff --git a/docs/usage.rst b/docs/usage.rst --- a/docs/usage.rst +++ b/docs/usage.rst @@ -1,4 +1,277 @@ .. _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*. +