Provided by: percona-toolkit_2.2.7-1~dfsg1_all bug

NAME

       pt-agent - Agent for Percona Cloud Tools

SYNOPSIS

       Usage: pt-agent [OPTIONS]

       pt-agent is the client-side agent for Percona Cloud Tools.  It is not a general command
       line tool like other tools in Percona Toolkit, it is configured and controlled through the
       web at https://cloud.percona.com.  Visit https://cloud.percona.com for more information
       and to sign up.

DESCRIPTION

       pt-agent is the client-side agent for Percona Cloud Tools (PCT).  It is controlled and
       configured through the web app at https://cloud.percona.com.  Visit
       https://cloud.percona.com for more information and to sign up.

       pt-agent, or "the agent", is a single, unique instance of the tool running on a server.
       Two agents cannot run on the same server (see "--pid").

       The agent is a daemon that runs as root.  It should be started with "--daemonize".  It
       connects periodically to Percona to update its configuration and services, and it
       schedules "--run-service" and "--send-data" instances of itself using cron.  Other than
       "INSTALLING" and starting the agent locally, all control and configuration is done through
       the web at https://cloud.percona.com.

INSTALLING

       pt-agent must be installed and ran as root.  It is possible to run as a non-root user, but
       this requires a more complicated and manual installation.  Please contact Percona for help
       if you need to run pt-agent as a non-root user.

       Installing the agent as root is very simple:

         # pt-agent --install

       The agent will prompt you for your Percona Cloud Tools API key.  Then it will verify the
       API key, create a MySQL user for the agent, and run the agent.  When the install process
       is complete, go to https://cloud.percona.com to enable services for agent.

       Please contact Percona if you need help installing the agent.

   SLAVE INSTALL
       There are two ways to install pt-agent on a slave.  The first and best way is to install
       the agent on the master so that the "MYSQL USER" is created on the master and replicates
       to slaves.  This is best because it avoids writing to the slave.  Then create the
       "/etc/percona/agent/" directory on the slave and copy in to it "/etc/percona/agent/my.cnf"
       from the master.  Run "--install" on the slave and pt-agent will automatically detect and
       use the MySQL user and password in "/etc/percona/agent/my.cnf".  Repeat the process for
       other slaves.

       The second way to install pt-agent on a slave is not safe because it writes directly to
       the slave: specify "--install-options" "force_dangerous_slave_install" in addition to
       "--install".  As the install option name implies, this is dangerous, but it forces pt-
       agent to ignore that MySQL is a slave.

   Percona XtraDB Cluster (PXC) INSTALL
       Installing pt-agent on Percona XtraDB Cluster (PXC) nodes is the same as installing it
       safely on slaves.  First install the agent on any node.  This will create the "MYSQL USER"
       that will replicate to all other nodes.  Then create the "/etc/percona/agent/" directory
       on another node and copy in to it "/etc/percona/agent/my.cnf" from the first node where
       pt-agent was installed.  Run "--install" on the node and pt-agent will automatically
       detect and use the MySQL user and password in "/etc/percona/agent/my.cnf".  Repeat the
       process for other nodes.

MYSQL USER

       During "--install", pt-agent creates the following MySQL user:

         GRANT SUPER, USAGE ON *.* TO 'pt_agent'@'localhost' IDENTIFIED BY 'pass'

       "pass" is a random string.  MySQL options for the agent are stored in
       "/etc/percona/agent/my.cnf".  The "SUPER" privilege is required so that the agent can set
       global MySQL variables like "long_query_time".

EXIT STATUS

       pt-agent exists zero if no errors or warnings occurred, else it exits non-zero.

OPTIONS

       "--run-service" and "--send-data" are mutually exclusive.

       "--status", "--stop", and "--reset" are mutually exclusive.

       --[no]agent-api
           default: yes

           Enable the agent API; do not use this option manually.  This option is used internally
           to allow the agent to stop itself and shutdown quickly.

       --agent-uuid
           type: string

           Existing agent UUID for re-installing an agent.

       --api-key
           type: string

           Your secret Percona Cloud Tools API key.

       --ask-pass
           Prompt for MySQL password.

       --check-interval
           type: time; default: 1m

           How often to check for a new configuration and services.

       --config
           type: Array

           Read this comma-separated list of config files; if specified, this must be the first
           option on the command line.

           See the "--help" output for a list of default config files.

       --daemonize
           Daemonize the agent.  This causes the agent to fork into the background and "--log"
           all output.

           Fork to the background and detach from the shell.  POSIX operating systems only.

       --defaults-file
           short form: -F; type: string

           Only read MySQL options from the given file.  You must give an absolute pathname.

       --disk-bytes-free
           type: size; default: 100M

           Stop all services if the disk has less than this much free space.  This prevents the
           agent from filling up the disk with service data.

           Valid size value suffixes are k, M, G, and T.

       --disk-pct-free
           type: int; default: 5

           Stop all services if the disk has less than this percent free space.  This prevents
           the agent from filling up the disk with service data.

           This option works similarly to "--disk-bytes-free" but specifies a percentage margin
           of safety instead of a bytes margin of safety.  The agent honors both options, and
           will not collect any data unless both margins are satisfied.

       --help
           Print the agent's help and exit.

       --host
           short form: -h; type: string; default: localhost

           MySQL host.

       --install
           Install pt-agent as root.

       --install-options
           type: Hash

           Comma-separated list of "--install" options.  Options are:

           offline
               Do not verify the API key or start the agent.

           force_dangerous_slave_install
               Like the option's name suggests: this forces a dangerous slave install, so you
               should not use this option unless you are aware of the potential consequences.  To
               install the agent on a slave, "/etc/percona/agent/my.cnf" must exist because it is
               not safe to create the agent's MySQL user on a slave.  The agent should be
               installed on the master first, then "/etc/percona/agent/my.cnf" copied from the
               master server to the slave server.  Using this option forces the agent to create
               the agent's MySQL user on the slave.  WARNING: writing to a slave is dangerous and
               could cause replication to crash.

       --interactive
           Run in interactive mode (disables "--[no]log-api").

       --lib
           type: string; default: /var/lib/pt-agent

           Directory in which to save local data.  pt-agent is remotely controlled and
           configured, but it also saves data locally.  These files should not be edited
           manually.

       --log
           type: string; default: /var/log/pt-agent.log

           Log all output to this file when daemonized.

       --[no]log-api
           default: yes

           Log everything through the Percona Cloud Tools API.

       --password
           short form: -p; type: string

           MySQL password.

       --pid
           type: string; default: /var/run/pt-agent.pid

           Create the given PID file.  The file contains the process ID of the script.  The PID
           file is removed when the script exits.  Before starting, the script checks if the PID
           file already exists.  If it does not, then the script creates and writes its own PID
           to it.  If it does, then the script checks the following: if the file contains a PID
           and a process is running with that PID, then the script dies; or, if there is no
           process running with that PID, then the script overwrites the file with its own PID
           and starts; else, if the file contains no PID, then the script dies.

       --ping
           Ping the Percona Cloud Tools API and exit.

       --port
           short form: -P; type: int

           MySQL port number.

       --reload
           Force pt-agent to reload its configuration immediately.

       --reset
           cumulative: yes; default: 0

           Reset pt-agent to a clean post-install state.

           WARNING: all "--spool" data will be deleted.

       --run-service
           type: string

           Run a service and spool its data for "--send-data".  You do not need to run pt-agent
           with this option.  The main pt-agent daemon schedules instances of itself with this
           option.

       --send-data
           type: string

           Send data for a service to Percona.  You do not need to run pt-agent with this option.
           The main pt-agent daemon schedules instances of itself with this option.

       --set-vars
           type: Array

           Set the MySQL variables in this comma-separated list of "variable=value" pairs.

           By default, the agent sets:

              wait_timeout=10000

           Variables specified on the command line override these defaults.  For example,
           specifying "--set-vars wait_timeout=500" overrides the default value of 10000.

           The agent prints a warning and continues if a variable cannot be set.

       --socket
           short form: -S; type: string

           MySQL socket file.

       --spool
           type: string; default: /var/spool/pt-agent

           Directory in which to save service data before sending to Percona.  "--run-service"
           saves data in this directory, and "--send-data" reads data from this directory.  Each
           service has its own subdirectory, like "--spool/query-history" for the Query History
           service.  Data is removed by "--send-data" after it is successfully sent to Percona.

       --status
           Print the status of pt-agent.

       --stop
           Stop pt-agent and all services.

       --uninstall
           Completely remove pt-agent and all its data from the server.  This does not delete the
           agent from https://cloud.percona.com.

       --user
           short form: -u; type: string

           MySQL user, if not the current system user.

       --version
           Print the agent's version and exit.

DSN OPTIONS

       These DSN options are used to create a DSN.  Each option is given like "option=value".
       The options are case-sensitive, so P and p are not the same option.  There cannot be
       whitespace before or after the "=" and if the value contains whitespace it must be quoted.
       DSN options are comma-separated.  See the percona-toolkit manpage for full details.

       •   A

           dsn: charset; copy: yes

           Default character set.

       •   D

           copy: no

           Default database when connecting.

       •   F

           dsn: mysql_read_default_file; copy: yes

           Defaults file for connection values.

       •   h

           dsn: host; copy: yes

           MySQL host.

       •   p

           dsn: password; copy: yes

           MySQL password.

       •   P

           dsn: port; copy: yes

           MySQL port number.

       •   S

           dsn: mysql_socket; copy: no

           MySQL socket file.

       •   u

           dsn: user; copy: yes

           MySQL user, if not the current system user.

ENVIRONMENT

       The environment variable "PTDEBUG" enables verbose debugging output to STDERR.  To enable
       debugging and capture all output to a file, run the tool like:

          PTDEBUG=1 pt-agent ... > FILE 2>&1

       Be careful: debugging output is voluminous and can generate several megabytes of output.

SYSTEM REQUIREMENTS

       pt-agent requires:

       •   A Percona Cloud Tools account (https://cloud.percona.com)

       •   Access to https://cloud-api.percona.com

       •   Perl 5.8 or newer

       •   Standard Linux bin tools (grep, awk, stat, etc.)

       •   cron

       •   A Bash shell

       •   Core Perl modules

       •   DBD::mysql Perl module

       •   JSON Perl module

       •   LWP (>= v5.813) Perl module

       •   IO::Socket::SSL Perl module

BUGS

       For a list of known bugs, see <http://www.percona.com/bugs/pt-agent>.

       Please report bugs at <https://bugs.launchpad.net/percona-toolkit>.  Include the following
       information in your bug report:

       •   Complete command-line used to run the tool

       •   Tool "--version"

       •   MySQL version of all servers involved

       •   Output from the tool including STDERR

       •   Input files (log/dump/config files, etc.)

       If possible, include debugging output by running the tool with "PTDEBUG"; see
       "ENVIRONMENT".

DOWNLOADING

       Visit <http://www.percona.com/software/percona-toolkit/> to download the latest release of
       Percona Toolkit.

AUTHORS

       Daniel Nichter

ABOUT PERCONA TOOLKIT

       This tool is part of Percona Toolkit, a collection of advanced command-line tools
       developed by Percona for MySQL support and consulting.  Percona Toolkit was forked from
       two projects in June, 2011: Maatkit and Aspersa.  Those projects were created by Baron
       Schwartz and developed primarily by him and Daniel Nichter, both of whom are employed by
       Percona.  Visit <http://www.percona.com/software/> for more software developed by Percona.

COPYRIGHT, LICENSE, AND WARRANTY

       This program is copyright 2013-2014 Percona LLC and/or its affiliates.

       THIS PROGRAM IS PROVIDED "AS IS" AND WITHOUT ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING,
       WITHOUT LIMITATION, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR
       PURPOSE.

       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, version 2; OR
       the Perl Artistic License.  On UNIX and similar systems, you can issue `man perlgpl' or
       `man perlartistic' to read these licenses.

       You should have received a copy of the GNU General Public License along with this program;
       if not, write to the Free Software Foundation, Inc., 59 Temple Place, Suite 330, Boston,
       MA  02111-1307  USA.

VERSION

       pt-agent 2.2.7