"Fossies" - the Fresh Open Source Software Archive

Member "vnstat-2.9/INSTALL" (3 Sep 2021, 6585 Bytes) of package /linux/misc/vnstat-2.9.tar.gz:


As a special service "Fossies" has tried to format the requested text file into HTML format (style: standard) with prefixed line numbers. Alternatively you can here view or download the uninterpreted source code file. See also the last Fossies "Diffs" side-by-side code changes report for "INSTALL": 2.7_vs_2.8.

    1 
    2 # tl;dr
    3 
    4     ./configure --prefix=/usr --sysconfdir=/etc && make && make install
    5 
    6 
    7 # Prerequisites
    8 
    9  - make
   10  - C compiler
   11  - user with access to kernel interface statistics
   12    - usually available by default but can be restricted for example
   13      by grsecurity and similar security enhancement suites or settings
   14  - sqlite3     (library and development files)
   15  - libgd       (optional, image output)
   16  - check       (optional, test suite)
   17  - pkg-config  (optional, for check detection)
   18  - autotools   (optional, for recreating configure and makefiles)
   19 
   20 
   21 # Compiling the binaries
   22 
   23 This source package contains the required source files for vnStat including
   24 the daemon (`vnstatd`) and image output (`vnstati`). Executing
   25 
   26     ./configure --prefix=/usr --sysconfdir=/etc && make
   27 
   28 will compile `vnstat` and `vnstatd`. The optional image output capable binary
   29 `vnstati` will also be compiled if the required additional libgd library is
   30 found to be available and `--disable-image-output` isn't given as parameter
   31 for `./configure`.
   32 
   33 An example cgi (`vnstat.cgi`) to be used with a http server with the image
   34 output support has been provided in the `examples` directory. Configuration
   35 options for the cgi are in the beginning of the file. Additional examples
   36 for using the json output are also available in the same directory.
   37 
   38 For executing the optional test suite, see the appendix at the end of this
   39 file.
   40 
   41 
   42 # Installing as root
   43 
   44 Log in as root and run the following command:
   45 
   46     make install
   47 
   48 If there were no errors, vnStat binaries, man pages and a configuration
   49 file should now be installed. The configuration file will be upgraded using
   50 previously configured values if it is found already to exist. A backup
   51 of the previous configuration file will be named as `vnstat.conf.old` in the
   52 current directory.
   53 
   54 The configuration file `/etc/vnstat.conf` should be checked at this point.
   55 See the `vnstat.conf` man page for documentation about available options.
   56 
   57 Finally, make vnStat monitor available interfaces. Configure init scripts
   58 so that the following command is executed once during system startup:
   59 
   60     vnstatd -d
   61 
   62 The `examples` directory contains suitable files for most commonly used
   63 service managers. Refer to your operating system / distribution
   64 documentation if unsure which service manager is being used.
   65 
   66  * systemd
   67 
   68    * option 1: hardened - requires a more recent systemd version
   69     ~~~
   70     cp -v examples/systemd/vnstat.service /etc/systemd/system/
   71     systemctl enable vnstat
   72     systemctl start vnstat
   73     ~~~
   74 
   75    * option 2: simple - works also with older systemd versions
   76     ~~~
   77     cp -v examples/systemd/simple/vnstat.service /etc/systemd/system/
   78     systemctl enable vnstat
   79     systemctl start vnstat
   80     ~~~
   81 
   82  * init.d
   83 
   84    * Debian
   85     ~~~
   86     cp -v examples/init.d/debian/vnstat /etc/init.d/
   87     update-rc.d vnstat defaults
   88     service vnstat start
   89     ~~~
   90 
   91    * Red Hat / CentOS
   92     ~~~
   93     cp -v examples/init.d/redhat/vnstat /etc/init.d/
   94     chkconfig vnstat on
   95     service vnstat start
   96     ~~~
   97 
   98  * upstart
   99     ~~~
  100     cp -v examples/upstart/vnstat.conf /etc/init/
  101     initctl start vnstat
  102     ~~~
  103 
  104 An alternative method is to add the command to an already existing
  105 script that gets executed during system startup. In many distributions
  106 `/etc/rc.local` can be used if nothing else suitable can be found. Note
  107 that the full path to the executable may need to be included instead of
  108 only the command itself.
  109 
  110 During first startup, the daemon (`vnstatd`) should list and add all
  111 available interfaces for monitoring. Depending on configuration, it may
  112 take some minutes for the `vnstat` command to begin showing results as
  113 the entries in the database aren't updated constantly.
  114 
  115 Monitoring of unwanted interfaces can be stopped with:
  116 
  117     vnstat --remove -i ethunwanted
  118 
  119 
  120 # Installing without root access
  121 
  122 Copy all needed binaries to some directory included in your PATH
  123 (`~/bin/` is used here as an example) and create the database directory.
  124 
  125     cp -v vnstat vnstatd vnstati ~/bin/
  126     cp -v cfg/vnstat.conf ~/.vnstatrc
  127     mkdir ~/.vnstat
  128 
  129 Check that the binaries got installed to a suitable location and are of the
  130 correct version:
  131 
  132     vnstat --version
  133 
  134 If this gives a `command not found` error or a different than expected
  135 version then check the content of the PATH variable and try again.
  136 
  137 Next open the configuration file `~/.vnstatrc` with your favorite text editor
  138 and locate the following line:
  139 
  140     DatabaseDir "/var/lib/vnstat"
  141 
  142 and replace it with
  143 
  144     DatabaseDir "/pathtomyhomedir/.vnstat"
  145 
  146 Next, locate the following lines:
  147 
  148     UseLogging 2
  149     LogFile "/var/log/vnstat/vnstat.log"
  150     PidFile "/var/run/vnstat/vnstat.pid"
  151 
  152 and replace them with
  153 
  154     UseLogging 1
  155     LogFile "/pathtomyhomedir/.vnstat/.log"
  156     PidFile "/pathtomyhomedir/.vnstat/.pid"
  157 
  158 Finally, save the file. If you are unsure about your home directory path, execute
  159 
  160     cd ; pwd
  161 
  162 The output should tell your home directory.
  163 
  164 Now it's time to add a crontab entry for vnStat in order to get the daemon
  165 running automatically after a system startup. Do that by executing the
  166 command `crontab -e` and add the following line (without leading spaces,
  167 remember to change the path):
  168 
  169     @reboot ~/bin/vnstatd -d
  170 
  171 If you found yourself using a strange editor then `man vi` may help.
  172 
  173 Make sure the configuration file (`~/.vnstatrc`) has the log option either
  174 disabled or set to a file that is located in a place where you have write
  175 permissions, such as your home dir. Then try starting the daemon with
  176 
  177     vnstatd -d
  178 
  179 After that wait for (or generate) at least 1 byte of network traffic
  180 (and 5 min for the next database file save).
  181 
  182     vnstat
  183 
  184 Now you should get some statistics about your network usage. See the config
  185 file `~/.vnstatrc` for interface and other settings.
  186 
  187 
  188 # Appendix: Running the test suite
  189 
  190 This step isn't mandatory for using vnStat.
  191 
  192 The source package includes a test suite for validating many of the
  193 functionalities provided and used by the executables. The test suite requires
  194 the Check unit testing framework ( https://libcheck.github.io/check/ ) to be
  195 installed and available. Depending on the used distribution, the necessary
  196 package to be installed is usually called `check` and may also require
  197 `check-devel` to be installed if available. After the `./configure` script has
  198 been executed the test suite can be executed with:
  199 
  200     make check
  201 
  202 The output should show a non-zero number of tests executed if all the
  203 necessary packages were available. A more detailed list of executed tests
  204 can be seen from the `check_vnstat.log` file after execution.