Provided by: percona-toolkit_2.2.7-1~dfsg1_all 
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
perl v5.18.2 2014-02-20 PT-AGENT(1p)