Provided by: vnstat_2.10-2_amd64 bug

NAME

       vnstat - a console-based network traffic monitor

SYNOPSIS

       vnstat [-5bDedhlmqstvy?]  [--add] [--alert output exit type condition limit unit] [--begin
       date] [--config file] [--days [limit]] [--dbdir directory] [--dbiflist  [mode]]  [--debug]
       [--end  date]  [--fiveminutes [limit]] [--help] [-hg] [--hours [limit]] [--hoursgraph] [-i
       interface] [--iface interface] [--iflist [mode]] [--json [mode] [limit]]  [--limit  limit]
       [--live  [mode]]  [--locale  locale]  [--longhelp]  [--months  [limit]] [--oneline [mode]]
       [--query] [--rateunit [mode]] [--remove] [--rename name] [-ru [mode]]  [--setalias  alias]
       [--short]  [--showconfig] [--style number] [--top [limit]] [-tr [time]] [--traffic [time]]
       [--version] [--xml [mode] [limit]] [--years [limit]] [interface]

DESCRIPTION

       vnStat is a console-based network traffic monitor. It keeps a log of  5  minute  interval,
       hourly, daily, monthly and yearly network traffic for the selected interface(s).  However,
       it isn't a packet sniffer. The traffic  information  is  read  from  the  proc(5)  or  sys
       filesystems  depending  on  availability  resulting  in  light  use  of  system  resources
       regardless of network traffic rate.  That  way  vnStat  can  be  used  even  without  root
       permissions on most systems.

       Functionality  is  divided  into  two  commands.  The  purpose of the vnstat command is to
       provide an interface for querying the traffic information stored in the  database  whereas
       the daemon vnstatd(8) is responsible for data retrieval, caching and storage. Although the
       daemon process is constantly running as a service, it is actually  spending  most  of  its
       time sleeping between data updates.

OPTIONS

       --add  Create database entry for interface specified with -i or --iface option. The daemon
              can be running during this operation and will automatically  start  monitoring  the
              interface  without  a  restart  within SaveInterval minutes if configuration option
              RescanDatabaseOnSave is enabled. Otherwise the daemon  needs  to  be  restarted  in
              order for the added interface to be monitored.

       --alert output exit type condition limit unit
              Depending on values of given parameters, show alert, use different exit status or a
              combination of both when configured situation is met.

              output parameter takes a number from 0 to 3 and  controls  when,  if  at  all,  the
              command  will  result  in  output.  '0'  never produces output, '1' always produces
              output, '2' shows output only when usage  estimate  exceeds  limit  and  '3'  shows
              output only when limit is exceeded.

              exit  parameter  takes  a  number  from  0 to 3 and controls the exit status of the
              command. '0' always uses exit status 0, '1' always uses exit  status  1,  '2'  uses
              exit  status  1 if usage estimate exceeds limit but otherwise exit status 0 and '3'
              uses exit status 1 if limit is exceeded but otherwise exit status 0.

              type parameter defines to which  time  range  type  usage  the  limit  is  compared
              against.  Available  options:  'h',  'hour',  'hourly',  'd',  'day', 'daily', 'm',
              'month', 'monthly', 'y', 'year', 'yearly'.

              condition parameter defines if limit is  compared  to  received  (rx),  transmitted
              (tx),  total  or  estimated  usage  of  these three. Available options: 'rx', 'tx',
              'total', 'rx_estimate', 'tx_estimate', 'total_estimate'.

              limit is a greater than zero integer without decimals  which  defines  the  traffic
              usage  limit  using  the  unit  defined  with the unit parameter.  unit accepts the
              following options: 'B', 'KiB', 'MiB', 'GiB', 'TiB', 'PiB', 'EiB', 'KB', 'MB', 'GB',
              'TB',  'PB',  'EB'.  Usage  must  exceed  limit in order for the alarm to activate.
              Exactly the same usage as limit does not raise the alarm.

              Estimate calculation isn't limited to the estimate options in  condition  parameter
              but can also be achieved by using the estimate option in output or exit parameters.
              Missing or invalid parameters will result in --alert  specific  help  output  being
              shown.

       -b, --begin date
              Begin  the  list  output with a specific date / time defined by date instead of the
              begin being selected based on the number of entries to be  shown.   If  date  isn't
              available  in the database then the closest later date will be used.  date supports
              the following formats: YYYY-MM-DD HH:MM, YYYY-MM-DD and "today".  This  option  can
              only be used with --json , --xml and list outputs.

       --config file
              Use file as configuration file instead of using automatic configuration file search
              functionality. If --config is used multiple times, the configuration settings  from
              files  later  on  the command line will override configuration settings loaded from
              earlier files if the settings defined in the files overlap.

       -d, --days [limit]
              Show traffic statistics on a daily basis for the last days. The length of the  list
              will  be  limited  to 30 entries unless configured otherwise or unless the optional
              limit parameter is used. All entries stored in the database will be shown if  limit
              is set to 0.

       --dbdir directory
              Use directory as database directory instead of using the directory specified in the
              configuration file or the hardcoded default if no configuration file is available.

       --dbiflist [mode]
              List interfaces currently in the database. If mode is not defined or is  set  to  0
              then  the  output  will use a one line verbose format. If mode is set to 1 then the
              output will contain one interface per line. See also --iflist.

       -D, --debug
              Show additional debug output.

       -e, --end date
              End the list output with a specific date / time defined  by  date  instead  of  the
              latest  date  /  time in the database. If date isn't available in the database then
              the closest earlier date will be used.  date supports the following formats:  YYYY-
              MM-DD  HH:MM  and YYYY-MM-DD.  This option can only be used with --json , --xml and
              list outputs. The top list also requires --begin to be used at the same  time  with
              this option.

       -5, --fiveminutes [limit]
              Show  traffic statistics with a 5 minute resolution for the last hours.  The length
              of the list will be limited to 24 entries unless configured otherwise or unless the
              optional  limit parameter is used. All entries stored in the database will be shown
              if limit is set to 0.

       -h, --hours [limit]
              Show traffic statistics on a hourly basis. The length of the list will  be  limited
              to 24 entries unless configured otherwise or unless the optional limit parameter is
              used. All entries store in the database will be shown if the limit is set to 0.

       -hg, --hoursgraph
              Show traffic statistics on a hourly basis for the last 24 hours using a  bar  graph
              followed by a table representing the numerical data.

       -i, --iface interface
              Select  one  specific interface and apply actions to only it. For database queries,
              it is possible to merge the  information  of  two  or  more  interfaces  using  the
              interface1+interface2+...   syntax. All provided interfaces must be unique and must
              exist in the database when the merge syntax is used. Optionally, depending  on  the
              InterfaceMatchMethod  configuration  setting,  interface can be replaced with alias
              previously set using --setalias.  Merge syntax isn't supported when alias is  used.
              The  -i,  --iface  option is optional and interface can be used as parameter on the
              command line for selecting  the  used  interface  even  without  the  option  being
              explicitly used.

       --iflist [mode]
              List currently available interfaces. If mode is not defined or is set to 0 then the
              output will use a one line verbose format. If mode is set to 1 then the output will
              contain one interface per line. See also --dbiflist.

       --json [mode] [limit]
              Show  database content for selected interface or all interfaces in json format. All
              traffic values in the output are in bytes. An optional mode parameter can  be  used
              for  limiting  the  output  to  only  selected information.  Everything is shown by
              default. Setting mode to 's' will output a summary containing the last 2 entries of
              5 minute, hourly, daily, monthly and yearly resolution data, 'f' will output only 5
              minute resolution entries, 'h' hours, 'd' days, 'm' months, 'y' years and  't'  the
              top days. Alternatively or in combination with mode an optional limit parameter can
              be used to limit the number of entries in the output. The --json option can be used
              in  combination  with  -l,  --live and -tr options without mode or limit having any
              effect to the output. The jsonversion field in the output contains the API  version
              information.  It  will  be  changed only when the names or structures of previously
              existing content gets changed. In comparison, the vnstatversion field  exists  only
              as extra information.

       --limit limit
              Set the maximum number of shown entries in list outputs to limit.  Usage of --limit
              overrides the default list entry limit values  and  the  optional  limit  parameter
              given  directly  for a list query. All entries stored in the database will be shown
              if limit is set to 0.  --limit can also be used to control the length of --json and
              --xml outputs.

       -l, --live [mode]
              Display  current  transfer  rate  for  the  selected  interface  in real time until
              interrupted. Statistics will be shown after interruption if the  runtime  was  more
              than  10  seconds.  An  optional  mode  parameter can be used to select between the
              displaying of packets per second (mode 0) and transfer  counters  (mode  1)  during
              execution.  --style can also be used to affect the layout of the output. The output
              will be in json format if used in combination with --json option.

       --locale locale
              Use locale instead of using the locale setting specified in the configuration  file
              or the system default if no configuration file is available.

       --longhelp
              Show complete options list.

       -m, --months [limit]
              Show  traffic  statistics on a monthly basis for the last months. The length of the
              list will be limited to 12  entries  unless  configured  otherwise  or  unless  the
              optional  limit parameter is used. All entries stored in the database will be shown
              if limit is set to 0.

       --oneline [mode]
              Show traffic summary for selected interface using one line with a parsable  format.
              The  output  contains  15  fields  with  ;  used  as field delimiter. The 1st field
              contains the API version information of the output that will  only  be  changed  in
              future  versions if the field content or structure changes. The following fields in
              order 2) interface name, 3) timestamp for today, 4) rx for today, 5) tx for  today,
              6)  total  for  today,  7) average traffic rate for today, 8) timestamp for current
              month, 9) rx for current month, 10) tx for current month,  11)  total  for  current
              month,  12)  average traffic rate for current month, 13) all time total rx, 14) all
              time total tx, 15) all time total traffic.  An optional mode parameter can be  used
              to force all fields to output in bytes without the unit itself shown.

       -q, --query
              Force database query mode.

       --remove
              Delete  the  database entry for the interface specified with -i or --iface and stop
              monitoring  it.  The  daemon  can  be  running  during  this  operation  and   will
              automatically detect the change.

       --rename name
              Rename  the  interface  specified  with -i or --iface in the database with new name
              name.  The new name cannot already exist in the database.  This  operation  doesn't
              cause any data loss. The daemon should not be running during this operation.

       -ru, --rateunit [mode]
              Swap  the  configured  rate  unit. If rate has been configured to be shown in bytes
              then rate will be shown in bits if this option is present. In the same way, if rate
              has  been configured to be shown in bits then rate will be shown in bytes when this
              option is present. Alternatively, mode with either 0 or 1 can be used as  parameter
              for this option in order to select between bytes (0) and bits (1) regardless of the
              configuration file setting.

       --setalias alias
              Set alias as an alias for the selected interface to be shown in  queries.  The  set
              alias  can  be  removed by specifying an empty string for alias.  The daemon can be
              running during this operation.

       -s, --short
              Use short output mode. This mode is also used  when  more  than  one  interface  is
              available in the database and no specific interface is selected.

       --showconfig
              Show  current  configuration using the same format as the configuration file itself
              uses.

       --style number
              Modify the content and style of outputs. Set number to 0 for a narrower  output,  1
              for  enabling  bar  column,  2  for  same as previous but with average traffic rate
              visible in summary output and 3 for enabling average traffic rate  in  all  outputs
              where  it  is  supported.  4 disables the use of terminal control characters in -l,
              --live and -tr, --traffic modes.

       -t, --top [limit]
              Show all time top traffic days. The length of  the  list  will  be  limited  to  10
              entries unless configured otherwise or unless the optional limit parameter is used.
              All entries stored in the database will be shown if limit is set to  0.  When  used
              with  --begin and optionally with --end, the list will be generated using the daily
              data instead of separate top entries.  The availability of daily data  defines  the
              boundaries the date specific query can access.

       -tr, --traffic [time]
              Calculate  how  much  traffic  goes through the selected interface during the given
              time seconds. The time will be 5 seconds if a number parameter isn't specified. The
              output  will  be in json format if used in combination with --json option. However,
              in that case, the countdown before results isn't shown.  --style can also  be  used
              to affect the layout of the output.

       -v, --version
              Show current version.

       --xml [mode] [limit]
              Show  database  content for selected interface or all interfaces in xml format. All
              traffic values in the output are in bytes. An optional mode parameter can  be  used
              for  limiting  the  output  to  only  selected information.  Everything is shown by
              default. Setting mode to 's' will output a summary containing the last 2 entries of
              5 minute, hourly, daily, monthly and yearly resolution data, 'f' will output only 5
              minute resolution entries, 'h' hours, 'd' days, 'm' months, 'y' years and  't'  the
              top days. Alternatively or in combination with mode an optional limit parameter can
              be used to limit the number of entries in the output. The xmlversion field  in  the
              output contains the API version information. It will be changed only when the names
              or structures of previously existing  content  gets  changed.  In  comparison,  the
              vnstatversion field exists only as extra information.

       -y, --years [limit]
              Show  traffic  statistics  on a yearly basis for the last years. The list will show
              all entries by default unless configured otherwise or  unless  the  optional  limit
              parameter  is  used. All entries stored in the database will also be shown if limit
              is set to 0.

       -?, --help
              Show a command option summary.

FILES

       /var/lib/vnstat/
              Default database directory.

       /etc/vnstat.conf
              Config file that will be used unless $HOME/.vnstatrc exists. See vnstat.conf(5) for
              more information.

EXAMPLES

       vnstat Display  traffic summary for the default interface or multiple interfaces when more
              than one is monitored.

       vnstat -i eth0+eth1+eth3
              Display traffic summary for a merge of interfaces eth0, eth1 and eth3.

       vnstat -i eth2 --xml
              Output all information about interface eth2 in xml format.

       vnstat --json
              Output all information of all monitored interfaces in json format.

       vnstat -i eth0 --setalias local
              Give interface eth0 the alias "local". That information will be later visible as  a
              label when eth0 is queried.

       vnstat -i eth2 --remove
              Delete database entries for interface eth2 and stop monitoring it.

RESTRICTIONS

       Updates  need  to  be  executed  at  least as often as it is possible for the interface to
       generate enough traffic to overflow the kernel interface traffic counter. Otherwise, it is
       possible  that  some  traffic  won't  be seen. With 32-bit interface traffic counters, the
       maximum time between two updates depends on how fast the interface  can  transfer  4  GiB.
       Note that there is no guarantee that a 64-bit kernel has 64-bit interface traffic counters
       for all interfaces. Calculated theoretical times are:

              10 Mbit:        54 minutes
              100 Mbit:        5 minutes
              1000 Mbit:      30 seconds

       Virtual and aliased interfaces cannot be monitored  because  the  kernel  doesn't  provide
       traffic information for that type of interfaces. Such interfaces are usually named eth0:0,
       eth0:1, eth0:2 etc. where eth0 is the actual interface being aliased.

       Using long date output formats may cause misalignment in shown columns if  the  length  of
       the date exceeds the fixed size allocation.

AUTHOR

       Teemu Toivola <tst at iki dot fi>

SEE ALSO

       vnstatd(8), vnstati(1), vnstat.conf(5), proc(5), ifconfig(8), units(7)