From b76f290fbd375ef9525dd0e1a961ad06e2f2e041 Mon Sep 17 00:00:00 2001 From: Teemu Toivola Date: Sat, 3 Mar 2018 21:23:46 +0200 Subject: [PATCH] documentation update --- INSTALL | 23 ++++++++++++++--------- INSTALL_BSD | 28 ++++++++++++++++------------ README | 20 ++++---------------- README.md | 2 +- UPGRADE | 7 ++++--- man/vnstat.1 | 2 +- man/vnstat.conf.5 | 2 +- man/vnstatd.1 | 2 +- man/vnstati.1 | 2 +- 9 files changed, 43 insertions(+), 45 deletions(-) diff --git a/INSTALL b/INSTALL index bd03d1e..883df64 100644 --- a/INSTALL +++ b/INSTALL @@ -23,11 +23,14 @@ Compiling the binaries libgd2-noxpm libgd2-noxpm-dev - An example cgi ('vnstat.cgi') to be used with http server with the image + An example cgi ('vnstat.cgi') to be used with a http server with the image output support has been provided in the 'examples' directory. Configuration options for the cgi are in the beginning of the file. Additional examples for using the json output are also available in the same directory. + For executing the optional test suite, see the appendix at the end of this + file. + Installing as root :::::::::::::::::: @@ -36,9 +39,9 @@ Installing as root make install - If there were no errors, vnStat binaries, man pages and a config file - should now be installed. The configuration file will be upgraded - using previously configured values if it is found already to exist. + If there were no errors, vnStat binaries, man pages and a configuration + file should now be installed. The configuration file will be upgraded using + previously configured values if it is found already to exist. The configuration file /etc/vnstat.conf should be checked at this point. See the vnstat.conf man page for documentation about available options. @@ -49,7 +52,8 @@ Installing as root vnstatd -d The 'examples' directory contains suitable files for most commonly used - service managers: + service managers. Refer to your operating system / distribution + documentation if unsure which service manager is being used. systemd: cp -v examples/systemd/vnstat.service /etc/systemd/system/ @@ -88,7 +92,7 @@ Installing without root access :::::::::::::::::::::::::::::: Copy all needed binaries to some directory included in your PATH - (~/bin/ is an example) and create the database directory. + (~/bin/ is used here as an example) and create the database directory. cp -v vnstat vnstatd vnstati ~/bin/ cp -v cfg/vnstat.conf ~/.vnstatrc @@ -102,8 +106,8 @@ Installing without root access If this gives an 'command not found' error or a different than expected version then check then content of the PATH variable and try again. - Next open the config file ~/.vnstatrc with your favorite text editor and - locate the following line: + Next open the configuration file ~/.vnstatrc with your favorite text editor + and locate the following line: DatabaseDir "/var/lib/vnstat" @@ -157,4 +161,5 @@ Appendix: Running the test suite make check The output should show a non-zero number of tests executed if all the - necessary packages were available. + necessary packages were available. A more detailed list of executed tests + can be seen from the check_vnstat.log file after execution. diff --git a/INSTALL_BSD b/INSTALL_BSD index 26db52c..eeafa3f 100644 --- a/INSTALL_BSD +++ b/INSTALL_BSD @@ -10,19 +10,22 @@ Compiling the binaries will compile 'vnstat' and 'vnstatd' without requiring additional libraries. The optional image output capable binary 'vnstati' will also be compiled if the required additional libgd2 library is found to be available. In - BSD ports libgd2 is usually named simply 'gd'. + BSD ports libgd2 is usually 'graphics/gd'. - An example cgi ('vnstat.cgi') to be used with http server with the image + An example cgi ('vnstat.cgi') to be used with a http server with the image output support has been provided in the 'examples' directory. Configuration options for the cgi are in the beginning of the file. Additional examples for using the json output are also available in the same directory. Some BSD users may need to provide correct CFLAGS and LDFLAGS paths to the configure script if the image output is wanted but the location of libgd2 - isn't automatically detected. For example: + isn't automatically detected. For example (using bash as shell): CFLAGS="-I/usr/local/include" LDFLAGS="-L/usr/local/lib" ./configure + For executing the optional test suite, see the appendix at the end of this + file. + Installing as root :::::::::::::::::: @@ -31,8 +34,8 @@ Installing as root make install - If there were no errors, vnStat binaries, man pages and a config file - should now be installed. The configuration file will be upgraded using + If there were no errors, vnStat binaries, man pages and a configuration + file should now be installed. The configuration file will be upgraded using previously configured values if it is found already to exist. The configuration file /usr/local/etc/vnstat.conf should be checked at @@ -67,8 +70,8 @@ Installing without root access cp -v cfg/vnstat.conf ~/.vnstatrc mkdir ~/.vnstat - Next open the config file ~/.vnstatrc with your favorite text editor and - locate the following line: + Next open the configuration file ~/.vnstatrc with your favorite text editor + and locate the following line: DatabaseDir "/var/lib/vnstat" @@ -113,12 +116,13 @@ Appendix: Running the test suite The source package includes a test suite for validating at least some of the functionalities provided by the executables. The test suite requires the Check unit testing framework ( https://libcheck.github.io/check/ ) to - be installed and available. The configure script also assumes that the - 'pkg-config' command is installed. That command is usually part of the - 'pkgconf' package. After the configure script has been executed the test - suite can be executed with: + be installed and available (usually 'devel/check' in ports). The configure + script also assumes that the 'pkg-config' command is installed. That command + is usually part of the 'devel/pkgconf' package. After the configure script has + been executed the test suite can be executed with: make check The output should show a non-zero number of tests executed if all the - necessary packages were available. + necessary packages were available. A more detailed list of executed tests + can be seen from the check_vnstat.log file after execution. diff --git a/README b/README index 0da20a7..7ebc3e3 100644 --- a/README +++ b/README @@ -42,22 +42,6 @@ Available options and documentation vnstat.conf configuration file -Usage tips -:::::::::: - - Most vnStat settings can be changed from the config file. The config - file is either ~/.vnstatrc or /etc/vnstat.conf depending which one is - found first. A new config file can be generated using current settings - with the following command: - - vnstat --showconfig >newconfig - - The config file contains comments before any settings describing with - the purpose and usage of each setting is. More detailed descriptions - about each setting and suggested usage can be found from the vnstat.conf - man page. - - Contacting the author ::::::::::::::::::::: @@ -68,3 +52,7 @@ Contacting the author The current version of vnStat is always available from http://humdi.net/vnstat/ + + Bug reports, improvement ideas, feature requests and pull requests should + be sent using the matching features on GitHub as those are harder to miss + or forget. diff --git a/README.md b/README.md index 5edcd78..8b9a6b2 100644 --- a/README.md +++ b/README.md @@ -33,4 +33,4 @@ In both cases, continue with instructions from the INSTALL or INSTALL_BSD file d **irc:** Vergo (IRCNet) **git:** https://github.com/vergoh/vnstat -Bug reports, improvement ideas, feature requests and pull requests should be done using the matching features on GitHub as those are harder to miss or forget. +Bug reports, improvement ideas, feature requests and pull requests should be sent using the matching features on GitHub as those are harder to miss or forget. diff --git a/UPGRADE b/UPGRADE index c585f60..77d3b42 100644 --- a/UPGRADE +++ b/UPGRADE @@ -27,11 +27,12 @@ New configuration settings Upgrading from versions 1.3 and later ::::::::::::::::::::::::::::::::::::: -1) Follow the normal install procedure, 'make install' will upgrade the +1) Follow the normal install procedure, 'make install' step will upgrade the configuration file if it exists in the usual location. All user settings - will be kept. However, unknown content will get clean away. + will be kept. However, unidentified content will get cleaned away. -2) Review the updated content of the configuration file. +2) Review the updated configuration file. Refer to the vnstat.conf man page + for more detailed documentation regarding each setting. 3) If the daemon (vnstatd) is used then restart the daemon after the configuration file has been updated. diff --git a/man/vnstat.1 b/man/vnstat.1 index de53b75..47534cf 100644 --- a/man/vnstat.1 +++ b/man/vnstat.1 @@ -1,4 +1,4 @@ -.TH VNSTAT 1 "FEBRUARY 2018" "version 1.18" "User Manuals" +.TH VNSTAT 1 "MARCH 2018" "version 1.18" "User Manuals" .SH NAME vnstat \- a console-based network traffic monitor diff --git a/man/vnstat.conf.5 b/man/vnstat.conf.5 index eee17e1..91ff341 100644 --- a/man/vnstat.conf.5 +++ b/man/vnstat.conf.5 @@ -1,4 +1,4 @@ -.TH VNSTAT.CONF 5 "FEBRUARY 2018" "version 1.18" "User Manuals" +.TH VNSTAT.CONF 5 "MARCH 2018" "version 1.18" "User Manuals" .SH NAME vnstat.conf \- vnStat configuration file diff --git a/man/vnstatd.1 b/man/vnstatd.1 index 47b1b36..cad6564 100644 --- a/man/vnstatd.1 +++ b/man/vnstatd.1 @@ -1,4 +1,4 @@ -.TH VNSTATD 1 "FEBRUARY 2018" "version 1.18" "User Manuals" +.TH VNSTATD 1 "MARCH 2018" "version 1.18" "User Manuals" .SH NAME vnstatd \- daemon based database updating for vnStat diff --git a/man/vnstati.1 b/man/vnstati.1 index b2d4f56..46ff73e 100644 --- a/man/vnstati.1 +++ b/man/vnstati.1 @@ -1,4 +1,4 @@ -.TH VNSTATI 1 "FEBRUARY 2018" "version 1.18" "User Manuals" +.TH VNSTATI 1 "MARCH 2018" "version 1.18" "User Manuals" .SH NAME vnstati \- png image output support for vnStat -- 2.40.0