Chapter 11 Proxy and Aggregator Installation

Chapter 11 Proxy and Aggregator Installation
Prev		Next

Table of Contents

11.1 Proxy Aggregator Architecture
11.2 Prerequisites
11.3 Installing the Proxy and Aggregator
11.4 Graphical Installation Wizard
11.5 Text-Based Installation
11.6 Unattended Installation
11.7 Starting and Stopping the Proxy and Aggregator
11.8 Configuration Options

This chapter describes the architecture of the various Proxy, Aggregator and Connector installations and the installation process for the Proxy and Aggregator components.

The MySQL Enterprise Monitor Aggregator requires a framework, or chassis, to handle the communications between the client application and the MySQL instance. The following frameworks are available:

MySQL Enterprise Monitor Proxy: the Proxy functions as the communications chassis for the Aggregator and is responsible for intercepting the communications between the client application and the MySQL instance. This enables the Aggregator to collect the raw query data sent from the client application to the MySQL instance. The MySQL Enterprise Monitor Proxy and Aggregator installer can install and configure both Proxy and Aggregator, or a standalone Aggregator if one of the MySQL connectors is used as the communications chassis. The client application must be configured to communicate with the MySQL Enterprise Monitor Proxy.
MySQL Connectors: the MySQL Connectors enable communication between the client application and the MySQL instance. If you intend to use a MySQL Connector as the communications framework for the MySQL Enterprise Monitor Aggregator, you must configure the Connector to communicate with the Aggregator. If you use a Connector with the Aggregator, you do not need to install the MySQL Enterprise Monitor Proxy.

11.1 Proxy Aggregator Architecture

This section describes the MySQL Enterprise Monitor Proxy and Aggregator architecture.

Default Architecture

The following diagram shows the MySQL Enterprise Monitor Proxy and Aggregator architecture.

Figure 11.1 MySQL Enterprise Monitor Proxy and Aggregator Architecture

Note

The MySQL Enterprise Monitor Proxy and Aggregator does not have to be installed on the same host as the monitored MySQL instance. You can install it on another host.

MySQL Enterprise Monitor Aggregator with Connector

Important

The MySQL Enterprise Monitor Aggregator is supported by the PHP Connector. The other Connectors do not require the Aggregator and can communicate directly with the MySQL Enterprise Service Manager once configured to do so. For more information on configuring the Connectors, see Chapter 12, Configuring Connectors.

11.2 Prerequisites

Important

If you are using the MySQL Enterprise Monitor 2.3 implementation of the Agent and Aggregator with a 3.0 MySQL Enterprise Service Manager, you must uninstall the 2.3 version before installing the MySQL Enterprise Monitor Proxy and Aggregator delivered with MySQL Enterprise Monitor 3.0.14.

Proxy and Aggregator Users

It is not recommended to install the MySQL Enterprise Monitor Proxy and Aggregator as root. It is recommended to create a user specifically for the Proxy and Aggregator and install the products as that user, usually the mysql user. The same is true for the MySQL Enterprise Monitor Aggregator installation.

The MySQL client-application user must have SELECT privileges on the mysql.inventory table. This table contains the server UUID which is required to report the Query Analyzer data to the MySQL Enterprise Service Manager. Use the GRANT statement. For example:

mysql> GRANT SELECT on mysql.inventory to 'user'@'localhost' IDENTIFIED BY 'password';

Performance Schema

If you are using the MySQL Enterprise Monitor Proxy and Aggregator to collect query performance data, you must ensure the statements_digest consumer in performance_schema.setup_consumers is disabled.

11.3 Installing the Proxy and Aggregator

Important

No installer is provided for MySQL Enterprise Monitor Proxy and Aggregator on Windows platforms at this time.

The following installations are possible:

Aggregator and Proxy: Proxy and Aggregator are installed and configured together.
Aggregator: Aggregator is installed without the Proxy. Only use this installation type if you intend to use the Aggregator with MySQL Connector/PHP.

The installer has the following filename convention:

mysqlmonitoraggregator-version_number-platform- architecture-installer.extension

where:

version_number is the version number of the product.
platform is the intended operating system for the installer.
architecture specified whether the installer is for 32- or 64-bit platforms. If no architecture is present, the installer is 32-bit.

The installers support the following installation types:

Graphical Installation Wizard
Text mode
Unattended mode

11.4 Graphical Installation Wizard

This section describes how to install the MySQL Enterprise Monitor Proxy and Aggregator together using the MySQL Enterprise Monitor Proxy and Aggregator Installation Wizard. This process is identical across all platforms, except where explicitly stated.

This installation package installs one of the following:

Proxy and Aggregator: installs both the Proxy and Aggregator.
Aggregator Only: installs the Aggregator only.

To install the MySQL Enterprise Monitor Proxy and Aggregator using the Graphical Installation Wizard, do the following:

Note

On UNIX and Linux platforms, ensure the installer is executable before you begin.

Starting the Installation

Run the installer as required by the operating system.
The language selection dialog is displayed. Choose a language and click Next.
On the Welcome dialog, click Forward.
The Installation Directory dialog is displayed.
Define an installation directory, or accept the default installation directory, and click Forward.
The component selection page is displayed.
If you choose Proxy and Aggregator, you must follow the steps in Installing the Proxy and Installing the Aggregator
If you choose Aggregator Only, you must follow the steps in Installing the Aggregator.

Important

There is no difference in the files installed. The Aggregator Only option installs all files, Proxy included, but only configures the Aggregator. The Proxy files are installed, but it is not configured or started by this installation choice. If you choose Aggregator Only and attempt to start the proxy, it will not start unless correctly configured.
Choose your installation type and click Forward.

Installing the Proxy

This section describes how to install the MySQL Enterprise Monitor Proxy. To install the MySQL Enterprise Monitor Proxy, do the following:

Enter the port number the Proxy uses to listen for incoming connections. The default port is 6446.
Select the communication protocol the Proxy uses to connect to the monitored MySQL instance.

Note

Socket is not available on Windows platforms.

If you intend to use socket to connect to the database, select Socket and click Forward to define the path to the socket you want to use. After the socket is defined, click Forward to proceed with the installation.
If you intend to use TCP/IP, select TCP/IP and click Forward to proceed with the installation.
The MySQL database configuration dialog is displayed.
Enter the hostname or IP address and the port number of the monitored MySQL instance.
Click Forward.
The Aggregator configuration dialog is displayed.
The Proxy installation configuration is completed. The MySQL Enterprise Monitor Aggregator installation configuration is described in Installing the Aggregator.

Installing the Aggregator

This section describes how to install the MySQL Enterprise Monitor Aggregator. To install the MySQL Enterprise Monitor Aggregator, do the following:

Complete the following fields on the Aggregator configuration dialog:
- Aggregator Port: the port the Aggregator listens on.
- Aggregator SSL Port: the port the Aggregator listens on for SSL communication.
- PEM Certificate file: the location of the PEM certificate.
- CA Certificate file: the location of the CA certificate.
Click Forward to continue.
The MySQL Enterprise Monitor options dialog is displayed.
Complete the MySQL Enterprise Monitor option fields. This information is used by the Aggregator to connect to the MySQL Enterprise Service Manager.
You must provide the following information:
- Hostname or IP address: the address of the MySQL Enterprise Service Manager installation.
- Tomcat SSL Port: the port Tomcat is listening on for SSL connections.
- Agent Username: the username of the Agent. These are the connection credentials the Aggregator uses to connect to the MySQL Enterprise Service Manager.
- Agent Password: the password of the Agent.
Click Forward. The Configuration Report is displayed.
Review the data in the Configuration Report to ensure all configuration settings are correct.
Click Forward to complete the installation.

11.5 Text-Based Installation

The steps and options of the text-based installation are identical to those described in Section 11.4, “Graphical Installation Wizard”.

Note

There is no text-mode installation available for Microsoft Windows platforms.

To start the text-based installer, do the following:

Run the installer with the following option:
```
--mode text
```
The following example shows how to start the text-mode installation on a 64-bit Linux system:
```
shell>./mysqlmonitoraggregator-3.0.14.3040-linux-x86-64bit-installer.bin --mode text
```
The text installation process starts.
Follow the instructions onscreen. The options and values are identical to those described in Section 11.4, “Graphical Installation Wizard”.

11.6 Unattended Installation

The MySQL Enterprise Monitor Proxy and Aggregator installers enable you to perform unattended installations. This is useful for large scale installations on multiple machines. The installations can be run using all required options on a command line, or by defining the required options in a configuration file and calling that file for each installation.

Unattended Installation Options

To display the installation options available, run the installer from the command line with the following option:

--help

The following options are available:

Table 11.1 MySQL Enterprise Monitor Proxy and Aggregator Installer Options

Option	Description
`--help`	Displays the help text listing all options available for the platform on which the installer was run. On Microsoft Windows platforms, this option does not output the list of options in the console window, but in a separate help window.
`--version`	Displays the product version. On Microsoft Windows platforms, this option does not output the version details in the console window, but in a separate help window.
`--debuglevel`	Sets the verbosity of the installation log. 0 is the lowest verbosity, 4 is the highest. Default value is 2.
`--debugtrace`	Sets the path and filename of the installation log file.
`--optionfile`	Sets the path and filename of the installation options file. For more information, see Unattended Installation with Options File.
`--installer-language`	Sets the language of the installation. Possible values are: `en`: English. Default value. `ja`: Japanese.
`--mode`	Sets the installation mode. This varies according to the platform. For example, on Linux-based systems, you can choose a GUI-based installer with `--mode gtk`, or choose a text-only, console-based installation with `--mode text`. The following is a list of the GUI-based installation options available: Windows: `Win32` OS X: `osx` Solaris: `xwindow` Linux: `gtk` (Default) and `xwindow`. `--mode` can also initiate text mode and unattended installations. `--mode text`: starts a text-only, console-based installation process. Text-based installation are not available on Windows platforms. `--mode unattended`: starts an unattended installation. For more information on unattended installations, see Unattended Installation from the Command Line and Unattended Installation with Options File.
`--unattendedmodeui`	Sets the graphical elements to use, if any, in the unattended installation. The following options are available: `none`: no pop-ups, or progress bars are displayed. Errors are displayed, if they occur. `minimal`: No user interaction is required and a progress bar is displayed showing the installation progress. Errors are displayed, if they occur. `minimalWithDialogs`:
`--installdir`	Sets the installation directory for the product.
`--use-external-glib`	Sets the glib to use, the one delivered in the installer (0, default), or the system glib (1).
`--monitorcomponent`	Specifies which component to install. The following options are available: `proxy`: installs both Proxy and Aggregator. This is the default. `aggregator`: installs the Aggregator only.
Proxy-Specific Options
`--proxyservicename`	Sets the unique service name for the Proxy service.
`--mysqlconnmethod`	Sets the connection method used by the proxy to connect to the monitored MySQL instance. The following options are available: `tcpip`: default value. `socket`: unavailable on Microsoft Windows platforms.
`--proxyport`	Sets the port the Proxy listens on for incoming connections. Default value is `6446`.
`--mysqlhost`	Sets the hostname or IP address of the monitored MySQL instance. Default value is `localhost`.
`--mysqlport`	Sets the port of the monitored MySQL instance. Default value is `3306`.
`--mysqlsocket`	Sets the socket used by the monitored MySQL instance.
Aggregator-specific Options
`--aggregatorservicename`	Sets the unique name for the Aggregator service. Default value is `mysql-monitor-aggregator`.
`--aggregatorport`	Sets the port the Aggregator listens on. Default value is `14000`.
`--aggregatorsslport`	Sets the SSL port the Aggregator listens on for secure connections. Default value is `14443`.
`--aggregatorsslcertfile`	Sets the location of the SSL certificate.
`--aggregatorsslcafile`	Sets the location of the SSL CA file.
`--managerhost`	Sets the hostname or IP address of the MySQL Enterprise Service Manager installation. Default value is `localhost`.
`--managerport`	Sets the SSL port number of the MySQL Enterprise Service Manager's Tomcat installation. Default value is `18443`.
`--agentuser`	Sets the agent username which the Aggregator uses to communicate with the MySQL Enterprise Service Manager. Default value is `agent`.
`--agentpassword`	Sets the password of the agent used by the Aggregator.

Unattended Installation from the Command Line

To run the unattended installation from the command line, enter the installer name, followed by the --mode unattended option, followed by the options you want to define. If you do not define an option on the command line, the default value is used, if a default exists. If no default value exists, you must define that value in the configuration after the installation is complete.

The following example installs MySQL Enterprise Monitor Proxy and Aggregator on a Linux platform but changes the MySQL Enterprise Service Manager values:

./mysqlmonitoraggregator-3.0.14.3041-linux-x86-b4bit-installer.bin --mode unattended 
--unattendedmodeui none --managerhost service.manager.com --agentuser Agent100 
--agentpassword D4unKotR

This example changes the following:

Instructs the installer to display no dialogs of any kind. In this mode, errors are displayed if they occur.
Sets the MySQL Enterprise Service Manager location to service.manager.com. This is the location of your MySQL Enterprise Service Manager installation. The default ports were not changed.
Sets the Agent username to Agent100 and the Agent password to D4unKotR.

Unattended Installation with Options File

If you use an options file, you add the options you want to change to a text file as name=value pairs. Using the example shown in Unattended Installation from the Command Line, the text file contents are:

      mode=unattended
      unattendedmodeui=none
      managerhost=service.manager.com
      agentuser=Agent100
      agentpassword=D4unKotR

If this file was saved as pa-options.txt, the installation command takes the following format:

/mysqlmonitoraggregator-3.0.14.3041-linux-x86-b4bit-installer.bin --optionfile pa-options.txt

11.7 Starting and Stopping the Proxy and Aggregator

This section describes how to start and stop the MySQL Enterprise Monitor Proxy and Aggregator.

On UNIX, Linux, and Mac OS X platforms, the Proxy and Aggregator processes are controlled using the scripts in the etc/init.d directory of your installation. On Windows platforms, you can start, stop and restart your services using the Start menu entries, or through the Services control of the Microsoft Management Console.

Important

If you install the MySQL Enterprise Monitor Proxy and Aggregator, both Proxy and Aggregator run under the name of the MySQL Enterprise Monitor Proxy, not as two distinct services. If you install the MySQL Enterprise Monitor Aggregator standalone, it is run as the MySQL Enterprise Monitor Aggregator.

init.d:
- Starting the Proxy and Aggregator: run ./mysql-monitor-proxy start .
- Stopping the Proxy and Aggregator: run ./mysql-monitor-proxy stop.
- Starting the Aggregator: run ./mysql-monitor-aggregator start.
  If you have installed both Proxy and Aggregator, do not run this command. The Aggregator is started by the Proxy-specific commands.
- Stopping the Aggregator: run ./mysql-monitor-aggregator stop.
  If you have installed both Proxy and Aggregator, do not run this command. The Aggregator is stopped by the Proxy-specific commands.
- Status: run either script with the status option to see the status of the service.
  If you installed both Proxy and Aggregator, the status returns information on the Proxy only. In this installation type, if the Proxy is running, the Aggregator is running also. For more information, check the mysql-monitor-proxy.log.
- Restarting: run either script, depending on your installation type, with the restart option to restart the services.

11.8 Configuration Options

It is possible to run the Proxy, or Aggregator, or both, with specific options, using the following files installed in the bin directory of your installation:

mysql-monitor-aggregator
mysql-monitor-proxy

Note

On Windows platforms, these files are executables and have the exe extension. On Linux, UNIX and Mac platforms, they are shell scripts.

To view the options available, run either file with the --help option.

The help output is broken down into the following sections:

Help Options: lists the various help output options.
Application Options: lists the application options.
aggr-module: lists the Aggregator-specific options. Displayed only for the --help-all option.
proxy-module: lists the Proxy-specific options. Displayed only for the --help-all option.

The mysql-monitor-aggregator help displays the application and Proxy module help, only. The mysql-monitor-proxy help displays application, aggregator and proxy output.

Table 11.2 Proxy and Aggregator Help Options

Option Name	Description
`-h`, `--help`	Lists the basic help options.
`--help-all`	Lists all available help options.
`--help-aggr`	Lists the Aggregator-specific help options.
`--help-proxy`	Lists the Proxy-specific help options. This option is only available on the `mysql-monitor-proxy` file.

Table 11.3 Application Options

Option Name	Description
`-V`, `--version`	Shows the version of the Proxy or Aggregator, depending on which file it is run with.
`--defaults-file=<file>`	Defines a configuration file to use. Similarly to running an unattended installation with an options file, this enables you to define all configuration changes as name-value pairs (without the `--` prefix for each option) and call the file as needed.
`--verbose-shutdown`	Configures the application to always log the exit code on shutdown.
`--daemon`	Configures the application to run in daemon mode.
`--user=<user>`	Defines the specific user to run the Aggregator.
`--basedir=<absolute path>`	Defines the absolute path of the base directory which is prefixed to all relative paths in the configuration. If you define a relative path, an error is returned.
`--pid-file=<file>`	Defines the name of the PID file to use in the event the application is started in daemon mode.
`--plugin-dir=<path>`	Defines the path to the plugins.
`--plugins-name=<name>`	Defines the names of the plugins to load. On the command line, you can specify this value multiple time. In the configuration file, the option is entered once, followed by a comma-separated list of the required plugins.
`--log-level=<string>`	Defines the logging level. Possible values are `critical` (default value), `error`, `warning`, `info`, `message`, and `debug`.
`--log-file=<filename>`	Defines the name of the logfile.
`--log-use-syslog`	Configures the application to send all messages to the syslog. UNIX/Linux only.
`--log-backtrace-on-crash`	Configures the application to invoke the debugger in the event of a crash.
`--keepalive`	Configures the application to attempt a restart in the event of a crash. Not available on Microsoft Windows. When running as a service, the Proxy automatically restarts.
`--max-open-files`	Configures the maximum number of open files.
`--event-threads`	Configures the number of event-handling threads. Default value is 1.
`--lua-path=<path>`	Sets the LUA_PATH.
`--lua-cpath=<path>`	Sets the LUA_CPATH

Table 11.4 aggr-module Options

Option Name	Description
`--aggr-address=<host:port>`	Defines the address and listening port of the Aggregator. The default port value is 14000.
`--aggr-lua-script=<filename>`	Defines the path to the LUA script.
`--aggr-mem-url=<url>`	Defines the URL to the MySQL Enterprise Service Manager.
`--aggr-mem-user=<string>`	Defines the Agent username to use for communication with the MySQL Enterprise Service Manager.
`--aggr-mem-password=<string>`	Defines the Agent password to use for communication with the MySQL Enterprise Service Manager.
`--aggr-ssl-address=<host:port>`	Defines the address and listening port of the Aggregator for SSL connections to the Aggregator.
`--aggr-ssl-cert-file=<filename>`	Defines the PEM server certificate for the Aggregator.
`--aggr-ssl-cs-file=<filename>`	Defines the CA certificate for the Aggregator.
`--aggr-ssl-ciphers=<string>`	Defines the supported ciphers.
`--aggr-test-mode`	Start the Aggregator in test mode. This mode ignores the flush interval setting and aggregates queries until instructed to return the aggregated data by a HTTP REST interface. It returns a JSON result set of all the normalized queries and their aggregated data.
`--aggr-flush-interval=<seconds>`	Defines the interval, in seconds, at which the query data is flushed to the MySQL Enterprise Service Manager. The default value is 60 seconds.
`--aggr-max-request-body-size=<bytes>`	Defines the maximum size of an HTTP request body. The default size is 1MB.

Table 11.5 proxy-module Options

Option Name	Description
`-P`, `--proxy-address=<host:port>`	The address and listening port of the Proxy. Default port is `4040`.
`-r`, `--proxy-read-only-backend-addresses`	The address and listening port of the remote, slave server. This is not set by default.
`-b`, `--proxy-backend-addresses=<host:port>`	The host name (or IP address) and port of the MySQL server to connect to. You can specify multiple backend servers by supplying multiple options. Clients are connected to each backend server in round-robin fashion. For example, if you specify two servers A and B, the first client connection will go to server A; the second client connection to server B and the third client connection to server A. When using this option on the command line, you can specify the option and the server multiple times to specify multiple backends. When using this option in a configuration file, separate multiple servers with commas.
`--proxy-skip-profiling`	Disable query profiling (statistics time tracking). The default is for tracking to be enabled.
`-s file_name`, `--proxy-lua-script=<file>`	The Lua script file to be loaded. The script file is not loaded and parsed until a connection is made. Also note that the specified Lua script is reloaded for each connection; if the content of the Lua script changes while the Proxy is running, the updated content is automatically used when a new connection is made.
`--no-proxy`	Disables the Proxy module. By default, the Proxy is enabled.
`--proxy-pool-no-change-user`	Disable use of the MySQL protocol CHANGE_USER command when reusing a connection from the pool of connections specified by the `proxy-backend-addresses` list.
`--proxy-connect-timeout`	Defines the Proxy's connection timeout in seconds. Default value is 2.
`--proxy-read-timeout`	Defines the read timeout in seconds. Default is 8 hours.
`--proxy-write-timeout`	Defines the write timeout in seconds. Default is 8 hours.

These options, with the exception of the help, version and defaults-file options, are also used, as name=value pairs, in the ini files used to configure the Proxy and Aggregator services.

The configuration files are located in the etc directory of your installation.

mysql-monitor-proxy.ini: configures the Proxy and Aggregator. Use this file when both components are installed.
mysql-monitor-aggregator.ini: configures the Aggregator. Use this file when only the Aggregator is installed.

Prev	Up	Next
Chapter 10 Configuration Utilities	Home	Chapter 12 Configuring Connectors