summaryrefslogtreecommitdiffabout
authorSergey Poznyakoff <gray@gnu.org.ua>2016-06-08 08:51:12 (GMT)
committer Sergey Poznyakoff <gray@gnu.org.ua>2016-06-08 08:51:12 (GMT)
commite1671fa83120afe14f3ed69dcafaa3fac64253ef (patch) (side-by-side diff)
treef52f2900ce5672abe396e53ec68254e5e65b233c
parent2a05c7dd59041edbd32d10dae9f6a66d7ba547a4 (diff)
downloadmysqlstat-e1671fa83120afe14f3ed69dcafaa3fac64253ef.tar.gz
mysqlstat-e1671fa83120afe14f3ed69dcafaa3fac64253ef.tar.bz2
Add manpages
Diffstat (more/less context) (ignore whitespace changes)
-rw-r--r--setup/.gitignore2
-rw-r--r--setup/Makefile.am19
-rw-r--r--setup/mysqlstat-setup.pl133
-rw-r--r--src/Makefile.am2
-rw-r--r--src/mysqlstat.8105
5 files changed, 250 insertions, 11 deletions
diff --git a/setup/.gitignore b/setup/.gitignore
new file mode 100644
index 0000000..2906366
--- a/dev/null
+++ b/setup/.gitignore
@@ -0,0 +1,2 @@
+/mysqlstat-setup
+/mysqlstat-setup.1
diff --git a/setup/Makefile.am b/setup/Makefile.am
index 2f40efa..a6eca15 100644
--- a/setup/Makefile.am
+++ b/setup/Makefile.am
@@ -1,14 +1,17 @@
-EXTRA_DIST=mysqlstat-setup.pl
+EXTRA_DIST=mysqlstat-setup.pl mysqlstat-setup.1
-all:;
+bin_SCRIPTS = mysqlstat-setup
+dist_man_MANS = mysqlstat-setup.1
-install-exec-local:
- test -d $(DESTDIR)$(bindir) || $(mkdir_p) $(DESTDIR)$(bindir)
+BUILT_SOURCES = mysqlstat-setup.1
+CLEANFILES=mysqlstat-setup
+
+mysqlstat-setup: mysqlstat-setup.pl
sed -e 's|[@]DLMODDIR[@]|@DLMODDIR@|' \
-e 's|[@]CONFDIR[@]|@CONFDIR@|' \
- $(srcdir)/mysqlstat-setup.pl > $(DESTDIR)$(bindir)/mysqlstat-setup
- chmod +x $(DESTDIR)$(bindir)/mysqlstat-setup
+ $(srcdir)/mysqlstat-setup.pl > mysqlstat-setup
+
+mysqlstat-setup.1: mysqlstat-setup.pl
+ perldoc -o nroff $(srcdir)/mysqlstat-setup.pl > mysqlstat-setup.1
-uninstall-local:
- rm -f $(DESTDIR)$(bindir)/mysqlstat-setup
diff --git a/setup/mysqlstat-setup.pl b/setup/mysqlstat-setup.pl
index eb54084..00988a2 100644
--- a/setup/mysqlstat-setup.pl
+++ b/setup/mysqlstat-setup.pl
@@ -26,7 +26,8 @@ B<mysqlstat-setup>
[B<--user=>I<USER>]
[B<--password=>I<PASSWORD>]
[B<--snmp-user=>I<USER>]
-[B<--snmp-password=>I<PASSWORD>]
+[B<--snmp-password=>I<PASSWORD>]
+[B<--snmp-host=>I<HOSTNAME>]
[B<--confdir> I<CONFDIR>]
[B<--libdir> I<LIBDIR>]
@@ -37,7 +38,135 @@ B<mysqlstat-setup>
=head1 DESCRIPTION
+This utility configures B<snmpd>(8) and B<mysqld>(8) servers for using
+the B<mysqlstat>(8) module. It performs the following actions:
+
+=over 4
+
+=item 1. Creates MySQL user and grants it the necessary privileges.
+
+By default the user B<snmp> is created with empty password. This can be
+controlled using the following command line options:
+
+=over 8
+
+=item B<--snmp-user=>I<USER>
+
+Sets the MySQL user name to use.
+
+=item B<--snmp-password=>I<PASSWORD>
+
+Sets the MySQL password.
+
+=item B<--snmp-host=>I<HOSTNAME>
+
+Sets the source host name or IP address to use. Default is B<localhost>.
+
+=back
+
+Credentials for connecting the MySQL server are read from file B<~/.my.cnf>,
+if such file exists. Another file may be given using the B<--defaults-file>
+option. Credentials can also be given from command line, using the options
+B<--user>, B<--password> and B<--host>, although such usage is not recommended
+for security reasons.
+
+=item 2. Creates the B</etc/snmp/mysqlstat.cnf> file.
+
+This file defines the MySQL credentials to use when connecting to the
+B<mysqld> server. If that file already exists, B<mysqlstat-setup> assumes the
+module has already been configured and refuses to run (unless given the
+B<--force> option).
+
+=item 3. Edits the B</etc/snmp/snmpd.conf> file.
+
+The B<dlmod> statement is inserted, which instructs B<snmpd> to load the
+module.
+
+=back
+
=head1 OPTIONS
+
+In most cases, it suffices to run the utility without any special options.
+Nevertheless, the following options are provided that alter its behavior:
+
+=over 4
+
+=item B<-f>, B<--force>
+
+Force operation even if it is detected that the B<mysqlstat> module has already
+been set up.
+
+=item B<-u>, B<--user=>I<USER>
+
+Connect to MySQL using I<USER> as user name. This user must have B<GRANT>
+privileges.
+
+B<Note:> it is not the user that will be used by the B<mysqlstat>
+module. For that, see B<--snmp-user>, below.
+
+=item B<-p>, B<--password=>I<PASSWORD>
+
+Connect to MySQL using the supplied password.
+
+B<Note:> it is not the password that the B<mysqlstat> module will be using.
+For that, see B<--snmp-password>, below.
+
+=item B<--host=>I<HOST>
+
+Connect to MySQL server running at I<HOST> (hostname or IP address). This will
+also be stored in F</etc/snmp/mysqlstat.cnf> for use by the B<mysqlstat> module.
+
+=item B<--defaults-file=>I<FILE>
+
+Read MySQL access credentials from I<FILE>. By default F<~/.my.cnf> is read
+if it exists. This way of supplying access credentials is preferred over
+the command line options.
+
+=item B<--snmp-user=>I<USER>
+
+MySQL user to be used by the B<mysqlstat> module. Default is B<snmp>.
+
+=item B<--snmp-password=>I<PASSWORD>
+
+MySQL password to be used by the B<mysqlstat> module. Default is empty
+password.
+
+=item B<--snmp-host=>I<HOSTNAME>
+
+Hostname or IP address the B<mysqlstat> module will connect from. This is
+used when granting MySQL user privileges.
+
+=item B<-C>, B<--confdir=>I<DIR>
+
+Assume I<DIR> instead of F</etc/snmp>.
+
+=item B<-L>, B<--libdir=>I<LIBDIR>
+
+Net-snmp modules are installed to I<LIBDIR>.
+
+=back
+
+The following options provide informational output:
+
+=over 4
+
+=item B<-h>
+
+Print short help summary.
+
+=item B<--help>
+
+Print the manpage.
+
+=item B<--usage>
+
+Show a terse command line usage summary.
+
+=back
+
+=head1 SEE ALSO
+
+B<mysqlstat>(8).
=cut
@@ -134,7 +263,7 @@ sub edit_cnf {
print $fd "[mysqlstat]\n";
print $fd "user=$snmp_user\n";
print $fd "password=$snmp_password\n" if $snmp_password;
- print $fd "host=$snmp_host\n" if $snmp_host and $snmp_host ne 'localhost';
+ print $fd "host=$mysql_host\n" if $mysql_host and $mysql_host ne 'localhost';
chown $owner_uid, $owner_gid, $fd;
close $fd;
umask($m);
diff --git a/src/Makefile.am b/src/Makefile.am
index 0b1ae43..c5810f9 100644
--- a/src/Makefile.am
+++ b/src/Makefile.am
@@ -56,6 +56,6 @@ AM_CPPFLAGS=\
mibdir=@MIBDIR@
mib_DATA = MYSQL-STAT-MIB.txt
-#dist_man_MANS = mysqlstat.8
+dist_man_MANS = mysqlstat.8
EXTRA_DIST = MYSQL-STAT-MIB.txt mysqlstat_mib.mib2c
diff --git a/src/mysqlstat.8 b/src/mysqlstat.8
new file mode 100644
index 0000000..f79e9cf
--- a/dev/null
+++ b/src/mysqlstat.8
@@ -0,0 +1,105 @@
+.\" This file is part of Mysqlstat -*- nroff -*-
+.\" 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/>.
+.TH MYSQLSTAT 8 "June 8, 2016" "mysqlstat"
+.SH NAME
+mysqlstat \- net-snmp module for collecting MySQL statistics
+.SH SYNOPSIS
+In \fBsnmpd.conf\fR(5):
+.PP
+.B dlmod mysqlstat_mib /usr/lib/snmp/mysqlstat.so
+.SH DESCRIPTION
+Dynamically loadable object module for
+.B net-snmp
+that provides access to
+.BR mysqld (8)
+statistics. The module is loaded into
+.BR snmpd (8)
+as shown in
+.BR SYNOPSIS .
+.PP
+The module provides access to the MySQL process list (as returned by
+.B SHOW PROCESSLIST
+command) and to replication status. The module connects to the MySQL
+server using credentials obtained from file
+.BR /etc/snmp/mysqlstat.cnf ,
+section
+.B [mysqlstat]
+(the file has the same format as the traditional
+.B /etc/my.cnf
+file). The MySQL user must be granted the
+.BR PROCESS ,
+and
+.B REPLICATION CLIENT
+privileges.
+.PP
+To configure the module, it is recommended to use the
+.BR mysqlstat\-setup (1)
+utility.
+.SH CONFIGURATION
+MySQL credentials are read from file
+.BR /etc/snmp/mysqlstat.cnf .
+The file has the standard MySQL ini file format. The section
+.B [mysqlstat]
+is read.
+.PP
+An example of \fBmysqlstat.cnf\fR follows:
+.PP
+.EX
+[mysqlstat]
+user=snmp
+password=guessme
+.EE
+.PP
+The file must be readable by the user
+.B snmpd
+runs as.
+.SH DEBUGGING
+The module defines the following debugging tokens:
+.TP
+.B mysqlstat_mib
+Enables general debugging information.
+.TP
+.B mysqlstat:sql
+Detailed information about SQL transactions.
+.SH OIDS
+See the file
+.BR MYSQL-STAT-MIB.txt ,
+for a detailed list of provided OIDs.
+.SH SEE ALSO
+.BR snmpd.conf (5),
+.BR snmpd (8),
+.BR mysqlstat\-setup (1),
+.BR mysqld (8).
+.SH AUTHORS
+Sergey Poznyakoff
+.SH "BUG REPORTS"
+Report bugs to <gray@gnu.org>.
+.SH COPYRIGHT
+Copyright \(co 2016 Sergey Poznyakoff
+.br
+.na
+License GPLv3+: GNU GPL version 3 or later <http://gnu.org/licenses/gpl.html>
+.br
+.ad
+This is free software: you are free to change and redistribute it.
+There is NO WARRANTY, to the extent permitted by law.
+.\" Local variables:
+.\" eval: (add-hook 'write-file-hooks 'time-stamp)
+.\" time-stamp-start: ".TH [A-Z_][A-Z0-9_.-]* [0-9] \""
+.\" time-stamp-format: "%:B %:d, %:y"
+.\" time-stamp-end: "\""
+.\" time-stamp-line-limit: 20
+.\" end:

Return to:

Send suggestions and report system problems to the System administrator.