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.yaml in the current working dir. A
sample file can be generated by running:

.. code:: shell

    $ tranqap init
    Saved sample configuration to config.yaml

Here is how it looks like:

.. code:: yaml

    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
      filter_port: 22
  

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

.. code:: yaml

    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.yaml`` 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

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

Nothing is displayed 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

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

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

Run stop:

.. code:: shell

    tranqap> stop