diff options
author | Sergey Poznyakoff <gray@gnu.org.ua> | 2016-06-08 11:51:12 +0300 |
---|---|---|
committer | Sergey Poznyakoff <gray@gnu.org.ua> | 2016-06-08 11:51:12 +0300 |
commit | e1671fa83120afe14f3ed69dcafaa3fac64253ef (patch) | |
tree | f52f2900ce5672abe396e53ec68254e5e65b233c | |
parent | 2a05c7dd59041edbd32d10dae9f6a66d7ba547a4 (diff) | |
download | mysqlstat-e1671fa83120afe14f3ed69dcafaa3fac64253ef.tar.gz mysqlstat-e1671fa83120afe14f3ed69dcafaa3fac64253ef.tar.bz2 |
Add manpages
-rw-r--r-- | setup/.gitignore | 2 | ||||
-rw-r--r-- | setup/Makefile.am | 19 | ||||
-rw-r--r-- | setup/mysqlstat-setup.pl | 133 | ||||
-rw-r--r-- | src/Makefile.am | 2 | ||||
-rw-r--r-- | src/mysqlstat.8 | 105 |
5 files changed, 250 insertions, 11 deletions
diff --git a/setup/.gitignore b/setup/.gitignore new file mode 100644 index 0000000..2906366 --- /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 @@ -23,24 +23,153 @@ B<mysqlstat-setup> [B<--defaults-file=>I<FILE>] [B<--force>] [B<--host=>I<HOST>] [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>] B<mysqlstat-setup> [B<-h>] [B<--help>] [B<--usage>] =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 my $progname = basename($0); my $progdescr = 'Set up mysqlstat module'; @@ -131,13 +260,13 @@ sub edit_cnf { my $m = umask(077); open(my $fd, '>', $mysqlstat_cnf) or die "can't open $mysqlstat_cnf for writing: $!"; 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); } sub backup { diff --git a/src/Makefile.am b/src/Makefile.am index 0b1ae43..c5810f9 100644 --- a/src/Makefile.am +++ b/src/Makefile.am @@ -53,9 +53,9 @@ AM_CPPFLAGS=\ ${MYSQL_CFLAGS}\ -DCONFDIR=\"$(CONFDIR)\" 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 --- /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: |