Add documentation

11 files changed, 204 insertions, 56 deletions

diff --git a/Makefile.am b/Makefile.am
index 18821d9..df581f5 100644
--- a/Makefile.am
+++ b/Makefile.am
@@ -1,5 +1,5 @@
 # This file is part of Mysqlstat -*- autoconf -*-
-# Copyright (C) 2014-2016 Sergey Poznyakoff
+# Copyright (C) 2016 Sergey Poznyakoff
 #
 # Mysqlstat is free software; you can redistribute it and/or modify
 # it under the terms of the GNU General Public License as published by
diff --git a/NEWS b/NEWS
index e69de29..ed6df2a 100644
--- a/NEWS
+++ b/NEWS
@@ -0,0 +1,34 @@
+Mysqlstatb NEWS -- history of user-visible changes. 2016-06-08
+Copyright (C) 2016 Sergey Poznyakoff
+See the end of file for copying conditions.
+
+Please send Mysqlstat bug reports to <bug-mysqlstat@gnu.org.ua>
+
+Version 1.0, 2016-06-08
+
+Initial release.
+
+
+* Copyright information:
+
+Copyright (C) 2016 Sergey Poznyakoff
+
+   Permission is granted to anyone to make or distribute verbatim copies
+   of this document as received, in any medium, provided that the
+   copyright notice and this permission notice are preserved,
+   thus giving the recipient permission to redistribute in turn.
+
+   Permission is granted to distribute modified versions
+   of this document, or of portions of it,
+   under the above conditions, provided also that they
+   carry prominent notices stating who last changed them.
+
+Local variables:
+mode: outline
+paragraph-separate: "[	]*$"
+eval: (add-hook 'write-file-hooks 'time-stamp)
+time-stamp-start: "changes. "
+time-stamp-format: "%:y-%02m-%02d"
+time-stamp-end: "\n"
+end:
+
diff --git a/README b/README
index e69de29..87c029a 100644
--- a/README
+++ b/README
@@ -0,0 +1,104 @@
+Mysqlstat README
+Copyright (C) 2016 Sergey Poznyakoff
+See the end of file for copying conditions.
+
+* Introduction
+
+This file contains brief information about configuring, testing
+and using Mysqlstat. It is *not* intended as a replacement
+for the documentation, and is provided as a brief reference only.
+For a detailed documentation, please see the mysqlstat(8)
+manpage.
+
+* Overview
+
+Mysqlstat is a dynamically loadable object module for net-snmp
+snmpd, that provides access to process list statistics and replication 
+status of the mysqld server.
+
+* Installation
+
+In order to compile the package you need to have Net-SNMP and MySQL
+client installed.  The installation sequence is as usual:
+
+  ./configure [options]
+  make
+  make install
+
+(the last step normally requires root privileges).  For generic
+options to configure, please see the file INSTALL.  Package-specific
+options are:
+
+** --with-dlmoddir=DIR
+
+Install varnish_mod.so in DIR.  By default it is installed in
+$PREFIX/lib/snmp, where $PREFIX stands for the installation prefix.
+
+** --with-mibdir=DIR
+
+Install MIBs (the file MYSQL-STAT-MIB.txt) in DIR.  By default it is
+installed in $prefix/share/snmp.
+
+** --with-snmp-config-dir=DIR
+
+Net-SNMP configuration directory.  Default is $sysconfdir/snmp.
+
+To enable the module, run
+
+  mysqlstat-setup
+
+as root.  The utility will do the following:
+
+ - Create MySQL user and grant it the necessary privileges.
+ - Create the file mysqlstat.cnf in Net-SNMP configuration directory.
+ - Edit the file /etc/snmp/snmpd.conf
+
+In order to do that, it will need to connect to MySQL server as a user
+with GRANT privileges.  The preferred way to supply MySQL server credentials
+is by defining them in your ~/.my.cnf file.  You may use another file name
+using the --defaults-file option:
+
+  mysqlstat-setup --defaults-file=setup.cnf
+
+You can also use the familiar --user, --pasword and --host options to supply
+the credentials from the command line:
+
+  mysqlstat-setup --user=root --password=guessme
+
+By default, the MySQL user 'snmp'@'localhost' will be created (with
+empty password).  To change this use the following options:
+
+  --snmp-user=USER
+  --snmp-password=PASSWORD
+  --snmp-host=HOST_OR_IP
+
+For more details, refer to the manpage mysqlstat-setup(8).
+
+* Bug reporting
+
+Send bug reports and suggestions to <bug-mysqlstat@gnu.org.ua>.
+
+
+* Copyright information:
+
+Copyright (C) 2016 Sergey Poznyakoff
+
+   Permission is granted to anyone to make or distribute verbatim copies
+   of this document as received, in any medium, provided that the
+   copyright notice and this permission notice are preserved,
+   thus giving the recipient permission to redistribute in turn.
+
+   Permission is granted to distribute modified versions
+   of this document, or of portions of it,
+   under the above conditions, provided also that they
+   carry prominent notices stating who last changed them.
+
+
+Local Variables:
+mode: outline
+paragraph-separate: "[ 	]*$"
+version-control: never
+End:
+
+
+ 
\ No newline at end of file
diff --git a/configure.ac b/configure.ac
index 24bb003..3ecbdc2 100644
--- a/configure.ac
+++ b/configure.ac
@@ -1,5 +1,5 @@
 # This file is part of Mysqlstat -*- autoconf -*-
-# Copyright (C) 2014-2016 Sergey Poznyakoff
+# Copyright (C) 2016 Sergey Poznyakoff
 #
 # Mysqlstat is free software; you can redistribute it and/or modify
 # it under the terms of the GNU General Public License as published by
@@ -15,7 +15,7 @@
 # along with Mysqlstat.  If not, see <http://www.gnu.org/licenses/>.
 
 AC_PREREQ(2.69)
-AC_INIT([mysqlstat], 0.0.91, [gray@gnu.org])
+AC_INIT([mysqlstat], 1.0, [bug-mailstat@gnu.org])
 AC_CONFIG_SRCDIR(src/mysqlstat_mib.mib2c)
 AM_CONFIG_HEADER(config.h)
 AC_CONFIG_AUX_DIR([build-aux])
@@ -23,7 +23,8 @@ AC_CONFIG_MACRO_DIR([m4])
 
 AC_CANONICAL_SYSTEM
 AC_LANG(C)
-AM_INIT_AUTOMAKE([gnu tar-ustar])
+AM_INIT_AUTOMAKE([gnu tar-ustar silent-rules])
+AM_SILENT_RULES([yes])
 
 AC_GNU_SOURCE
 AC_PROG_CC
diff --git a/setup/Makefile.am b/setup/Makefile.am
index a6eca15..0aa4dfe 100644
--- a/setup/Makefile.am
+++ b/setup/Makefile.am
@@ -1,3 +1,19 @@
+# This file is part of Mysqlstat -*- automake -*-
+# Copyright (C) 2016 Sergey Poznyakoff
+#
+# Mysqlstat is free software; you can redistribute it and/or modify
+# it under the terms of the GNU General Public License as published by
+# the Free Software Foundation; either version 3, or (at your option)
+# any later version.
+#
+# Mysqlstat is distributed in the hope that it will be useful,
+# but WITHOUT ANY WARRANTY; without even the implied warranty of
+# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+# GNU General Public License for more details.
+#
+# You should have received a copy of the GNU General Public License
+# along with Mysqlstat.  If not, see <http://www.gnu.org/licenses/>.
+
 EXTRA_DIST=mysqlstat-setup.pl mysqlstat-setup.1
 
 bin_SCRIPTS = mysqlstat-setup
@@ -7,11 +23,11 @@ BUILT_SOURCES = mysqlstat-setup.1
 CLEANFILES=mysqlstat-setup
 
 mysqlstat-setup: mysqlstat-setup.pl
-	sed -e 's|[@]DLMODDIR[@]|@DLMODDIR@|' \
+	$(AM_V_GEN)sed -e 's|[@]DLMODDIR[@]|@DLMODDIR@|' \
             -e 's|[@]CONFDIR[@]|@CONFDIR@|' \
           $(srcdir)/mysqlstat-setup.pl > mysqlstat-setup
 
 mysqlstat-setup.1: mysqlstat-setup.pl
-	perldoc -o nroff $(srcdir)/mysqlstat-setup.pl > mysqlstat-setup.1
+	$(AM_V_GEN)perldoc -o nroff $(srcdir)/mysqlstat-setup.pl > mysqlstat-setup.1
 
 
diff --git a/setup/mysqlstat-setup.pl b/setup/mysqlstat-setup.pl
index 00988a2..6c8eecc 100644
--- a/setup/mysqlstat-setup.pl
+++ b/setup/mysqlstat-setup.pl
@@ -1,4 +1,19 @@
 #!/usr/bin/perl
+# This file is part of Mysqlstat 
+# Copyright (C) 2016 Sergey Poznyakoff
+#
+# Mysqlstat is free software; you can redistribute it and/or modify
+# it under the terms of the GNU General Public License as published by
+# the Free Software Foundation; either version 3, or (at your option)
+# any later version.
+#
+# Mysqlstat is distributed in the hope that it will be useful,
+# but WITHOUT ANY WARRANTY; without even the implied warranty of
+# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+# GNU General Public License for more details.
+#
+# You should have received a copy of the GNU General Public License
+# along with Mysqlstat.  If not, see <http://www.gnu.org/licenses/>.
 
 use strict;
 use DBI;
@@ -214,20 +229,30 @@ sub db_connect {
     $arg .= ":port=$mysql_port" if defined $mysql_port;
     $arg .= ":;mysql_read_default_file=$mysql_defaults_file"
         if defined $mysql_defaults_file;
+    my $my_cnf = "$ENV{HOME}/.my.cnf";
     if (!$arg
         or (!defined($mysql_user) and !defined($mysql_defaults_file))) {
-        my $my_cnf = "$ENV{HOME}/.my.cnf";
         if (-r $my_cnf) {
             error("info: using mysql option file $my_cnf");
             $arg .= ":;mysql_read_default_file=$my_cnf";
         }
     }
-    $arg = 'DBI:mysql'.$arg;
+    $arg = 'DBI:mysql'.($arg || ':');
 
     my $dbd = DBI->connect($arg, $mysql_user, $mysql_password,
 			   { PrintError => 0, AutoCommit => 1 });
     unless ($dbd) {
-	error("can't connect to MySQL server: ".$DBI::errstr);
+	error("can't connect to MySQL server: ".$DBI::errstr,
+          "This usually means that the credentials you supplied are incorrect.",
+	  "The utility needs to connect to the MySQL server as a user with GRANT",
+	  "privileges.  There are several ways of supplying the credentials:",
+	  "",
+	  "  1. In $my_cnf file.",
+	  "  2. In another MySQL option file.",
+	  "     In that case, use the option --defaults-file=FILENAME",
+	  "  3. Via command line options --user, --password, and --host.",
+	  "",
+	  "Please verify that the supplied options are correct and rerun $progname.");
 	exit EX_ERR;
     }
     return $dbd;
@@ -357,6 +382,11 @@ GetOptions("h" => sub {
 	   "force|f" => \$force
     ) or exit(EX_ERR);
 
+unless ($< == 0) {
+    error("must be run as root");
+    exit EX_ERR;
+}
+
 unless ($libdir =~ m#^/#) {
     error('NetSNMP library directory is not set',
       "It appears you invoked a copy of $progname that hasn't been installed.",
@@ -392,10 +422,6 @@ if (-e $mysqlstat_cnf and not $force) {
     exit EX_ERR;
 }
 
-unless ($< == 0) {
-    error("must be run as root");
-    exit EX_ERR;
-}
 unless (-d $confdir) {
     error("no such directory: $confdir");
     exit EX_ERR;
@@ -420,3 +446,5 @@ edit_cnf;
 # 3. Edit snmpd.conf
 edit_snmp_conf;
 
+print "$progname: Done.\n";
+print "$progname: Please restart snmpd in order for changes to make effect.\n";
diff --git a/src/Makefile.am b/src/Makefile.am
index c5810f9..c17447f 100644
--- a/src/Makefile.am
+++ b/src/Makefile.am
@@ -1,5 +1,5 @@
-# This file is part of Mysqlstat -*- autoconf -*-
-# Copyright (C) 2014-2016 Sergey Poznyakoff
+# This file is part of Mysqlstat -*- automake -*-
+# Copyright (C) 2016 Sergey Poznyakoff
 #
 # Mysqlstat is free software; you can redistribute it and/or modify
 # it under the terms of the GNU General Public License as published by
diff --git a/src/mysqlstat.c b/src/mysqlstat.c
index 2d32137..f599193 100644
--- a/src/mysqlstat.c
+++ b/src/mysqlstat.c
@@ -1,5 +1,5 @@
 /* This file is part of Mysqlstat
- * Copyright (C) 2014-2016 Sergey Poznyakoff
+ * Copyright (C) 2016 Sergey Poznyakoff
  *
  * Mysqlstat is free software; you can redistribute it and/or modify
  * it under the terms of the GNU General Public License as published by
@@ -14,7 +14,6 @@
  * You should have received a copy of the GNU General Public License
  * along with Mysqlstat.  If not, see <http://www.gnu.org/licenses/>.
  */
-
 #include <mysqlstat.h>
 #include <mysql/mysql.h>
 #undef NDEBUG
@@ -133,7 +132,7 @@ get_process_list(struct process_list **p)
 			plist.res = NULL;
 			plist.total = plist.active = plist.slaves = 0;
 		}
-		DEBUGMSGTL(("mysqlstat", "Getting process list\n"));
+		DEBUGMSGTL(("mysqlstat:sql", "Getting process list\n"));
 
 		conn = mysqlstat_connect();
 		if (!conn)
@@ -304,7 +303,7 @@ replSlaveStatusTable_load(netsnmp_cache *cache, void *vmagic)
 	if (!conn)
 		return SNMP_ERR_NOSUCHNAME;
 	
-	DEBUGMSGTL(("mysqlstat", "Getting slave status\n"));
+	DEBUGMSGTL(("mysqlstat:sql", "Getting slave status\n"));
 	if (mysql_query(&conn->mysql, "SHOW SLAVE STATUS")) {
 		snmp_log(LOG_ERR, "can't get slave status: %s\n",
 			 mysql_error(&conn->mysql));
@@ -469,40 +468,6 @@ process_slave_count(void)
 }
 
 
-#if 0
-unsigned replSlaveTable_timeout = CACHE_TIMEOUT;
-
-static void
-replSlaveTable_entry_free(struct replSlaveTable_entry *ent)
-{
-}
-
-int
-replSlaveTable_load(netsnmp_cache *cache, void *vmagic)
-{
-}
-
-void
-replSlaveTable_free(netsnmp_cache *cache, void *vmagic)
-{
-	netsnmp_tdata  *table = (netsnmp_tdata *) vmagic;
-	netsnmp_tdata_row *row;
-
-	DEBUGMSGTL(("mysqlstat", "freeing table\n"));
-	while ((row = netsnmp_tdata_row_first(table))) {
-		struct replSlaveTable_entry *entry = row->data;
-		free(ent->replSlaveHost);
-		free(ent->replSlaveUser);
-		free(ent->replSlaveCommand);
-		free(ent->replSlaveState);
-		free(ent->replSlaveInfo);
-		SNMP_FREE(ent);
-		netsnmp_tdata_remove_and_delete_row(table, row);
-	}
-}
-#endif
-
-
 
 
 
diff --git a/src/mysqlstat.h b/src/mysqlstat.h
index f4bf137..cc10749 100644
--- a/src/mysqlstat.h
+++ b/src/mysqlstat.h
@@ -1,5 +1,5 @@
 /* This file is part of Mysqlstat -*- autoconf -*-
- * Copyright (C) 2014-2016 Sergey Poznyakoff
+ * Copyright (C) 2016 Sergey Poznyakoff
  *
  * Mysqlstat is free software; you can redistribute it and/or modify
  * it under the terms of the GNU General Public License as published by
diff --git a/src/mysqlstat.mib2c b/src/mysqlstat.mib2c
index 0b2bd50..c38ffc9 100644
--- a/src/mysqlstat.mib2c
+++ b/src/mysqlstat.mib2c
@@ -1,5 +1,5 @@
 # This file is part of Mysqlstat -*- autoconf -*-
-# Copyright (C) 2014-2016 Sergey Poznyakoff
+# Copyright (C) 2016 Sergey Poznyakoff
 #
 # Mysqlstat is free software; you can redistribute it and/or modify
 # it under the terms of the GNU General Public License as published by
diff --git a/src/mysqlstat_mib.mib2c b/src/mysqlstat_mib.mib2c
index 510d9bf..45f8885 100644
--- a/src/mysqlstat_mib.mib2c
+++ b/src/mysqlstat_mib.mib2c
@@ -1,5 +1,5 @@
 # This file is part of Mysqlstat -*- c -*-
-# Copyright (C) 2014-2016 Sergey Poznyakoff
+# Copyright (C) 2016 Sergey Poznyakoff
 #
 # Mysqlstat is free software; you can redistribute it and/or modify
 # it under the terms of the GNU General Public License as published by