Repository
Munin (master)
Last change
2018-12-16
Graph Categories
Family
auto
Capabilities
Keywords
Language
Bash

ip_

Name

ip_ - Wildcard-plugin to monitor IP addresses (IPv4 or IPv6) through iptables

Configuration

This plugin needs to be run as root for iptables to work.

Additionally you can change the graph title from the IP address to a hostname by setting hostname in the configuration.

Example configuration follows. Only the first stanza is needed:

[ip_*]
  user root

[ip_192.168.0.1]
  env.hostname host.example.com

[ip_1080::8:800:200c:417a]
  env.hostname host6.example.com

Environment Variables

This plugin does not use environment variables.

Wildcard Plugin

This is a wildcard plugin. To monitor traffic to or from an IP address, link ip_<ipaddress> to this file.

For example,

ln -s /usr/share/munin/plugins/ip_ \
      /etc/munin/plugins/ip_192.0.2.1

will monitor the IP 192.0.2.1.

Iptables

You will need to set up iptables rules to create packet counters for incoming and outgoing traffic. The examples here cover how to create the rules. Given the multitude of methods used to configure iptables firewalls, they do not show how to make them survive a reboot.

Please also note that we do not intend to make this script compatible with anything but these rules made explicitly for the plugin. If you use a firewall tool to create iptables rules you may find that that will not work. Please add the appropriate lines by hand (or by hand-made script) if so.

Ipv4

In the case of a multihomed host, to monitor the local IP “192.0.2.1”, you will need the following rules:

iptables -I INPUT  -d 192.0.2.1
iptables -I OUTPUT -s 192.0.2.1

In the other case, for the remote IP “192.0.2.2”, you will need the following rules: (notice that the -s and -d are reversed)

iptables -I INPUT  -s 192.0.2.2
iptables -I OUTPUT -d 192.0.2.2

These rules will insert, at the top of the iptables chains INPUT and OUTPUT one rule which will act as a packet counter.

Since the rule does not include a “-j” argument, it will not explicitly allow or block anything.

Ipv6

If the IP address in the link contains a “:”, it is assumed to be a IPv6 address, and ip6tables are used instead of iptables to read the counters.

To create counters you will need to use “ip6tables” instead of “iptables”.

Same example as above, for the local IPv6 address “2001:db8::1” and remote “2001:db8::2”:

ip6tables -I INPUT  -d 2001:db8::1
ip6tables -I OUTPUT -s 2001:db8::1

ip6tables -I INPUT  -s 2001:db8::2
ip6tables -I OUTPUT -d 2001:db8::2

Bugs

None known.

Notes

This plugin is based on the if_ plugin.

Magic Markers

#%# family=auto
#%# capabilities=autoconf suggest

Author

Unknown. Suspected to be some Linpro employee.

License

Unknown.

#!/bin/bash

: << =cut

=head1 NAME

ip_ - Wildcard-plugin to monitor IP addresses (IPv4 or IPv6) through iptables

=head1 CONFIGURATION

This plugin needs to be run as root for iptables to work.

Additionally you can change the graph title from the IP address to a
hostname by setting hostname in the configuration.

Example configuration follows.  Only the first stanza is needed:

  [ip_*]
    user root

  [ip_192.168.0.1]
    env.hostname host.example.com

  [ip_1080::8:800:200c:417a]
    env.hostname host6.example.com


=head2 ENVIRONMENT VARIABLES

This plugin does not use environment variables.

=head2 WILDCARD PLUGIN

This is a wildcard plugin.  To monitor traffic to or from an IP
address, link ip_<ipaddress> to this file.

For example,

  ln -s /usr/share/munin/plugins/ip_ \
        /etc/munin/plugins/ip_192.0.2.1

will monitor the IP 192.0.2.1.

=head2 IPTABLES

You will need to set up iptables rules to create packet counters for
incoming and outgoing traffic.  The examples here cover how to create
the rules.  Given the multitude of methods used to configure iptables
firewalls, they do not show how to make them survive a reboot.

Please also note that we do not intend to make this script compatible
with anything but these rules made explicitly for the plugin.  If you
use a firewall tool to create iptables rules you may find that that
will not work.  Please add the appropriate lines by hand (or by
hand-made script) if so.

=head3 IPv4

In the case of a multihomed host, to monitor the local IP "192.0.2.1",
you will need the following rules:

  iptables -I INPUT  -d 192.0.2.1
  iptables -I OUTPUT -s 192.0.2.1

In the other case, for the remote IP "192.0.2.2", you will need the
following rules: (notice that the -s and -d are reversed)

  iptables -I INPUT  -s 192.0.2.2
  iptables -I OUTPUT -d 192.0.2.2

These rules will insert, at the top of the iptables chains INPUT and
OUTPUT one rule which will act as a packet counter.

Since the rule does not include a "-j" argument, it will not
explicitly allow or block anything.

=head3 IPv6

If the IP address in the link contains a ":", it is assumed to be a
IPv6 address, and ip6tables are used instead of iptables to read the
counters.

To create counters you will need to use "ip6tables" instead of
"iptables".

Same example as above, for the local IPv6 address "2001:db8::1" and
remote "2001:db8::2":

 ip6tables -I INPUT  -d 2001:db8::1
 ip6tables -I OUTPUT -s 2001:db8::1

 ip6tables -I INPUT  -s 2001:db8::2
 ip6tables -I OUTPUT -d 2001:db8::2

=head1 BUGS

None known.

=head1 NOTES

This plugin is based on the if_ plugin.

=head1 MAGIC MARKERS

 #%# family=auto
 #%# capabilities=autoconf suggest

=head1 AUTHOR

Unknown.  Suspected to be some Linpro employee.

=head1 LICENSE

Unknown.

=cut

. "$MUNIN_LIBDIR/plugins/plugin.sh"

IP=${0##*/ip_}
INPUT=${input:-INPUT}
OUTPUT=${output:-OUTPUT}
hostname=${hostname:-}

case $IP in
    *:*) # I know this! This is IPv6!
        # This is a fun hack to make the plugin ip6 compatible.
        # Suggested in ticket #439 by "jodal".
        eval 'iptables() {
            ip6tables "$@"
        }'
        ;;
esac

if [[ "$1" == "autoconf" ]]; then
    if [[ -r /proc/net/dev ]]; then
        if ! iptables -L "$INPUT" -v -n -w -x >/dev/null 2>/dev/null; then
            echo "no (could not run iptables as user $(whoami))"
            exit 0
        else
            echo yes
            exit 0
        fi
    else
        echo "no (/proc/net/dev not found)"
        exit 0
    fi
fi

if [[ "$1" == "suggest" ]]; then
    iptables -L "$INPUT" -v -n -x -w 2>/dev/null | awk --posix '$8 ~ /^([0-9]{1,3}\.){3}[0-9]{1,3}$/ { if (done[$8]!=1) {print $8; done[$8]=1;}}'
    if [[ -x /sbin/ip6tables ]]; then
        ip6tables -L "$INPUT" -v -n -x -w 2>/dev/null | awk --posix '$7 ~ /\/128$/ { if (done[$7]!=1) {a=$7;gsub(/\/128$/, "", a); print a; done[$7]=1;}}'
    fi
    exit 0
fi

if [[ "$1" == "config" ]]; then

    echo "graph_order out in"
    title=$IP
    if [[ "$hostname" ]]; then
        title="$hostname"
    fi
    echo "graph_title Interface $title traffic"
    echo 'graph_args --base 1000'
    # shellcheck disable=SC2016
    echo 'graph_vlabel bits per ${graph_period}'
    echo 'graph_category network'
    echo 'out.label sent'
    echo 'out.type DERIVE'
    echo 'out.min 0'
    echo 'out.cdef out,8,*'
    echo 'in.label received'
    echo 'in.type DERIVE'
    echo 'in.min 0'
    echo 'in.cdef in,8,*'
    print_warning out
    print_critical out
    print_warning in
    print_critical in
    exit 0
fi

# Escape .'s so they don't match _everything_?
escaped_ip=${IP//./\\.}
iptables -L "$INPUT" -v -n -x -w  | awk "/$escaped_ip"'[ /]/ { print "in.value " $2; exit 0; }'
iptables -L "$OUTPUT" -v -n -x -w | awk "/$escaped_ip"'[ /]/ { print "out.value " $2; exit 0; }'