Command Line Interface

Command Line Interface (CLI)

• Obtaining Status Information
• Application, Protocol and Category Lists
• Analysing a Packet Capture File
• Running the Agent in Debug Mode
• Further Reading

Netify Daemon Status

To view the current status of the Netify agent, execute:

sudo netifyd -s

The following can be helpful during troubleshooting:

• Agent is running / PID - Indicates whether the Netify DPI agent is running. If not stopped by user initiation, could indicates a configuration problem.
• Agent UUID - A unique identifier used during provisioning and API calls.
• API Updates - If not enabled, the agent will never communicate to any Netify cloud service. If you are using Netify Informatics, this must indicate enabled.
• API Application/Category Updates - An indication of whether the agent is able to receive continuous updates
• Active Flows - If zero, could indicate an issue with interface configuration.
• Maximum Memory Usage - Provides insight into how much RAM is being used during the heaviest load.
• Interface [Mode -> Capture Method] - Helps identify issues with your network interface packet capture configuration.
• Apps: NNNN, Domains: NNNN - If the number of apps is over 1500 it indicates you are using the commercial lists - otherwise, a sign that the open source signature list is in use.
• Persistent State Path - Reminder on where the configuration files and supporting folders are located.
• Volatile State Path - Reminder on where runtime data is written to as well as file sockets.

Application, Protocol and Category Lists

Applications and categories are determined using a set of signature and configuration files at run time. In contrast, protocols are compiled during the agents build time. The number of applications available to the netify agent is determined by type of signature list you are using. OEM integrators and Netify Informatics subscribers have access to the commercial signature files, and should see well over 1500 applications definitions. The open source list is restricted to 200 of the top ranking applications. The application signature file is found in:

/etc/netifyd/netify-apps.conf

The corresponding categories filename is:

/etc/netifyd/netify-categories.conf

Applications

Applications in Netify are imported at run time through the use of the Netify Application Signature file.

netifyd --dump-apps
    0: Unknown
    1: FTP/C
    2: POP3
    3: SMTP
    4: IMAP
    ...
    ..
    .

Protocols

Protocols are compiled in at run time. New and updated protocols are added in updated versions of the Netify agent.

netifyd --dump-protos
    0: Unknown
    1: FTP/C
    2: POP3
    3: SMTP
    4: IMAP
    ...
    ..
    .

Categories

Both applications and categories are group together in categories.

netifyd --dump-categories
    1: application: adult
    2: application: advertiser
    3: application: business
    4: application: cdn
    ...
    ..
    .
    1: protocol: authentication
    2: protocol: database
    3: protocol: file-server
    4: protocol: file-sharing
    ...
    ..
    .

Analysing a Packet Capture File

The Netify Agent can be used to perform offline analysis of a network file capture, regardless of the system architecture it was taken from or the bitrate during which it was captured.

Prior to analyzing a packet capture, version 5 requires the Core Processor Plugin to be installed, enabled and configured. In addition, we need to send the traffic analysis to a valid Netify Sink plugin. For this example, we'll send data to the Netify Sink Socket plugin and capture the data structures using a file socket.

First step, if you have't done so already, to install and enable the Core Processor and Sink Socket plugins. Once done, you can modify the default configuration files or use the ones provided below verbatim or as a template.

/etc/netifyd/netify-proc-core.json

{
    "sinks": {
        "sink-socket": {
            "default": {
                "enable": true,
                "types": [ "stream-flows", "stream-stats" ]
            }
        }
    }
}

/etc/netifyd/netify-sink-socket.json

{
    "channels": {
        "default": {
            "enable": true,
            "bind_address": "unix://${path_state_volatile}/netifyd.sock"
        }
    }
}

Real-Time Analysis

If you have not already done so, you can use tcpdump to create a capture file:

tcpdump -i eth0 -s 65536 -w /tmp/netify.pcap host 192.168.4.100

The -s (--snapshot-length) should be set to 65536 for smaller file sizes. The Netify Agent does not need anything beyond this limit for DPI analysis. Also, feel free to limit the capture to a specific host, port, or any other network filter expression supported by tcpdump. To see some bandwidth statistics, please run the capture for at least 60 seconds.

To playback a packet capture through the Netify agent in real-time, run:

sudo netifyd -d -v -t -r -I /path/to/pcap

Simultaneously, open another shell and capture the output that will now be sent to the file socket, located at /var/run/netifyd/netifyd.sock:

sudo netcat -U /var/run/netifyd/netifyd.sock | jq

You should see a stream of JSON data similar to the following:

{
  "flow": {
    "category": {
      "application": 27,
      "domain": 0,
      "network": 0,
      "protocol": 18
    },
    "detected_application": 10033,
    "detected_application_name": "netify.netify",
    "detected_protocol": 196,
    "detected_protocol_name": "HTTP/S",
    ...
    ..
    .
}

Fast Analysis

The -r flag forces Netify to analyze packets in the same timing in which they were captured. For example, if you have a 35 minute packet capture, this progress will take just over 35 minutes to process.

To modify this behaviour, remove the -r flag. Netify will process your packet capture as fast as it is capable of doing so - constrained by the resources of your system.

sudo netifyd -d -v -t -I /path/to/pcap

Delayed Start

There can be times where a delayed capture start is desirable. The most common case occurs when you are trying to capture the output through the sink processor. Binding to a socket cannot be done until the analysis is underway which makes it difficult to capture the output of the beginning of the packet capture.

To solve this case, add the --capture-delay 5 argument, where 5 can be any positive integer and represents the time to wait, in seconds, before analysing a capture file.

sudo netifyd --capture-delay 5 -d -v -t -I /path/to/pcap

Ignoring Interfaces

If you are using your agent to capture packets from the interfaces in real-time, but then want to use the same agent to analyze a packet capture file, it can be advantageous to temporarily disable the agent from listening on interfaces that would otherwise pollute the output.

To solve this case, add the --ignore-interface-configs argument.

sudo netifyd --ignore-interface-configs -d -v -t -I /path/to/pcap

Run Without Sources

If you are using your agent to send analysis to a sink, the agent can terminate before the last capture statistics are relayed to the sink plugin. To prevent this, use the --run-without-sources option. On completing the analysis, the agent will continue to run until the process is cancelled by the user (ex. CTRL-C or kill -p <>).

sudo netifyd --ignore-interface-configs --run-without-sources -d -v -t -I /path/to/pcap

Running the Agent in Debug Mode

During times of troubleshooting, it can be helpful to run the Netify agent in debug mode. This is especially true if you are creating a support email, as this information can be extermely helpful in finding a solution to your problem. To run in debug mode, simply stop any existing daemons that may be running, then execute Netify's executable with the -d argument. For additional verbosity, add the -v argument.

sudo systemctl stop netifyd
sudo netifyd -d -vvv

A sample of the output shown in debug mode is shown below.

offline0: i4pcugxXdfnrsFv TCP [OR] 142.250.80.35:443 ← [L] 192.168.2.100:60636
________  ______________  ___  __  _____________ ___ _  _  _____________ _____
1.        2.              3.   4.  5.            6.  7. 8. 9.            10.

1. Capture Source

The name of the capture source.

2. Flags

3. IP Protocol

The IP protocol in use.

4. and 8. Address Classification

First Letter

Second Letter

5. Lower IP Address

The IP address which mathmatically translates to the lower of the two IP addresses in the src and dst fields.

6. Lower Port

The port used on the lower IP.

7. Origin Direction

8. Address Classification

See 4 above.

9. Upper IP Address

The IP address which mathmatically translates to the upper of the two IP addresses in the src and dst fields.

10. Upper Port

The port used on the lower IP.

Further Reading

• Core Processor Output Formats
• Netify Debugging Reference