Quick start
===========

What follows is a very fast introduction for tranqap. It covers:

-  Configuration - add one remote machine as a target.
-  Verify that the target is capable of collecting network traffic.
-  Start packet capture.
-  Run wireshark.

Configuration
-------------

tranqap looks for a file named config.json in the current working dir. A
sample file can be generated by running:

.. code:: shell

    $ tranqap init
    Saved sample configuration to config.json

Here is how it looks like:

.. code:: json

    {
        "targets": [
            {
                "Name": "Target name. Informational identification only.",
                "Host": "Hostname/IP address of the target.",
                "Port": 22,
                "User": "SSH login.",
                "Key": "Path to private key, used for authentication.",
                "Destination": "Path to destination dir for the PCAP files.",
                "File Pattern": "Filename pattern for each pcap file. Index and file extension will be added to this string.",
                "File Rotation Count": 5,
                "Use sudo": true
            }
        ]
    }

All fields either contain sensible default value or informative
description. Here is an example of a working config file:

.. code:: json

    {
        "targets" : [
            {
                "Name": "Local target 1",
                "Host": "127.0.0.1",
                "Port": 2222,
                "User": "root",
                "Key": "ssh-key",
                "Destination": "PCAPs/local_target_1",
                "File Pattern": "trace",
                "File Rotation Count": 10,
                "Use sudo": false
            }
        ]
    }

Verify that the target is capable of collecting network traffic
---------------------------------------------------------------

The binary should be executed in the directory, where ``config.json`` is
located. The application uses a very basic shell as a UI:

.. code:: shell

    $ tranqap
    tranqap>

This is the tranqap prompt. **targets** command checks if tcpdump can be
run on the remote machine either with sudo or with a user capable to
collect network traffic without root.

.. code::

    tranqap> targets
    === Running checks for target <Local target 1> ===
    Check if tcpdump is installed: Yes
    Check if sudo is installed: NO
    Check if tcpdump can be run with sudo, without password: NO
    Check if tcpdump has got cap_net_admin capabilities: NO
    Check if tcpdump has got cap_net_raw+eip capabilities: NO
    User is member of the binary's group: Yes

    tranqap>

What this means:

-  tcpdump is installed on the remote machine. This is the packet
   capturer that tranqap uses.
-  sudo is not installed. This is fine, because the machine is accessed
   with root account.
-  tcpdump can be run with sudo, without requiring for password. Also
   fine - there is no sudo on the machine.
-  Last three lines are meaningful only if tranqap should run tcpdump with
   regular user. They are not relevant for the current case.

**WARNING** Collecting PCAPs as root is dangerous. This means that there
is a private key for the machine sitting unprotected on the filesystem.
Avoid this at all cost.

Start packet capture
--------------------

Just run start:

.. code:: shell

    tranqap> start
    tranqap>

Nothing happens but you should see a PCAP file is created in the output
directory, which is PCAPs/local\_target\_1:

.. code:: shell

    $ ls PCAPs/local_target_1/
    trace.pcap

Run wireshark
-------------

The traffic which is saved in the PCAP file can also be inspected in
real time with wireshark:

.. code:: shell

    tranqap> wireshark
    tranqap>

Wireshark should be started locally and all the traffic will be shown
there.

Stop capture
------------

Run stop:

.. code:: shell

    tranqap> stop
    tranqap>