'\"macro stdmacro
.\"
.\" Copyright (c) 2013 Red Hat.
.\" Copyright (c) 2013 Ryan Doyle.
.\"
.\" This program 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 2 of the License, or (at your
.\" option) any later version.
.\"
.\" This program 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.
.\"
.\"
.TH PMDANGINX 1 "PCP" "Performance Co-Pilot"
.SH NAME
\f3pmdanginx\f1 \- nginx performance metrics domain agent (PMDA)
.SH DESCRIPTION
\f3pmdanginx\f1 is a Performance Metrics Domain Agent (\s-1PMDA\s0) which
exports performance metrics from
.BR nginx (8)
\- an HTTP and reverse proxy server, a mail proxy server, and a generic
TCP proxy server.
.SH INSTALLATION
This \s-1PMDA\s0 requires that the
.B nginx
stub_status module is active and available at
.BR http://localhost/nginx_status .
.PP
In order to enable this module, the "server" section of the
.I nginx.conf
configuration file should contain the following.
.de CS
.in +0.5i
.ft CR
.nf
..
.de CE
.fi
.ft 1
.in
..
.PP
.CS
location /nginx_status {
    stub_status on;
    access_log off;
    allow 127.0.0.1;
    allow ::1;
    deny all;
}
.CE
.PP
Instrumentation availability can be verified using these
commands (compile-time then run-time checks):
.sp 1
.RS +4
.ft B
.nf
# nginx -V 2>&1 | grep -o with-http_stub_status_module
# curl http://localhost/nginx_status
.fi
.ft P
.RE
.sp 1
Install the nginx \s-1PMDA\s0 by using the Install script as root:
.sp 1
.RS +4
.ft B
.nf
# cd $PCP_PMDAS_DIR/nginx
# ./Install
.fi
.ft P
.RE
.sp 1
To uninstall, the following must be done as root:
.sp 1
.RS +4
.ft B
.nf
# cd $PCP_PMDAS_DIR/nginx
# ./Remove
.fi
.ft P
.RE
.sp 1
\fBpmdanginx\fR is launched by \fIpmcd\fR(1) and should never be executed
directly. The Install and Remove scripts notify \fIpmcd\fR(1) when the
agent is installed or removed.
.SH FILES
.IP "\fB$PCP_PMDAS_DIR/nginx/nginx.conf\fR" 4
optional configuration file for \fBpmdanginx\fR
.IP "\fB$PCP_PMDAS_DIR/nginx/Install\fR" 4
installation script for the \fBpmdanginx\fR agent
.IP "\fB$PCP_PMDAS_DIR/nginx/Remove\fR" 4
undo installation script for the \fBpmdanginx\fR agent
.IP "\fB$PCP_LOG_DIR/pmcd/nginx.log\fR" 4
default log file for error messages from \fBpmdanginx\fR
.SH PCP ENVIRONMENT
Environment variables with the prefix \fBPCP_\fR are used to parameterize
the file and directory names used by \fBPCP\fR. On each installation, the
file \fB/etc/pcp.conf\fR contains the local values for these variables.
The \fB$PCP_CONF\fR variable may be used to specify an alternative
configuration file, as described in \fIpcp.conf\fR(5).
.SH SEE ALSO
.BR PCPIntro (1),
.BR pmcd (1)
and
.BR nginx (8).