Skip to content
Percona Documentation

Set up PMM Client

There are different ways to install PMM Client on a node and register it with PMM Server. Choose from:

  • Docker: Run PMM Client as a Docker container.

  • Package manager:

    • On Debian or Red Hat Linux, install percona-release and use a Linux package manager (apt/dnf) to install PMM Client.
    • On Debian or Red Hat, download .deb/.rpm PMM Client packages and manually install them.

Binary is only way to install PMM client without root permissions

  • Binary package: For other Linux distributions, download and unpack generic PMM Client Linux binaries.

When you have installed PMM Client, you must:

If you need to, you can unregister, remove services or remove PMM Client.

Here’s an overview of the choices.

!image

Before you start

  • Set up PMM Server with a known IP address accessible from the client node.
  • You have superuser (root) access on the client host.
  • You have superuser access to any database servers that you want to monitor.
  • These Linux packages are installed: curl, gnupg, sudo, wget.
  • If using it, install Docker.

  • System requirements:

    • Operating system – PMM Client runs on any modern 64-bit Linux distribution. It is tested on supported versions of Debian, Ubuntu, CentOS, and Red Hat Enterprise Linux. (See Percona software support life cycle).
    • Disk – A minimum of 100 MB of storage is required for installing the PMM Client package.

    With a good connection to PMM Server, additional storage is not required. However, the client needs to store any collected data that it cannot dispatch immediately, so additional storage may be required if the connection is unstable or the throughput is low. VMagent uses 1 GB of disk space for cache during a network outage. QAN, on the other hand, uses RAM to store cache.

Install

Docker

The PMM Client Docker image is a convenient way to run PMM Client as a preconfigured Docker container.

  1. Pull the PMM Client docker image.

    docker pull \
percona/pmm-client:2

  2. Use the image as a template to create a persistent data store that preserves local data when the image is updated.

    docker create \
--volume /srv \
--name pmm-client-data \
percona/pmm-client:2 /bin/true

  3. Run the container to start PMM Agent in setup mode. Set X.X.X.X to the IP address of your PMM Server. (Do not use the docker --detach option as PMM agent only logs to the console.)

    PMM_SERVER=X.X.X.X:443
docker run \
--rm \
--name pmm-client \
-e PMM_AGENT_SERVER_ADDRESS=${PMM_SERVER} \
-e PMM_AGENT_SERVER_USERNAME=admin \
-e PMM_AGENT_SERVER_PASSWORD=admin \
-e PMM_AGENT_SERVER_INSECURE_TLS=1 \
-e PMM_AGENT_SETUP=1 \
-e PMM_AGENT_CONFIG_FILE=config/pmm-agent.yaml \
--volumes-from pmm-client-data \
percona/pmm-client:2

    Tips

    You can find a complete list of compatible environment variables here.

  4. Check status.

    docker exec pmm-client \
pmm-admin status

    In the PMM user interface you will also see an increase in the number of monitored nodes.

You can now add services with pmm-admin by prefixing commands with docker exec pmm-client.

Tips

  • Adjust host firewall and routing rules to allow Docker communications. (Read more)
  • For help: docker run --rm percona/pmm-client:2 --help

In the GUI.

  • Select PMM Dashboards → System (Node) → Node Overview.
  • In the Node Names menu, select the new node.
  • Change the time range to see data.

Danger

pmm-agent.yaml contains sensitive credentials and should not be shared.

Package manager

Tip

If you have used percona-release before, disable and re-enable the repository:

percona-release disable all
percona-release enable original release

  1. Configure repositories: 

    wget https://repo.percona.com/apt/percona-release_latest.generic_all.deb
dpkg -i percona-release_latest.generic_all.deb

  2. Install the PMM Client package: !!! hint “Root permissions” 

    apt update
apt install -y pmm2-client

  3. Check: 

    pmm-admin --version

  4. Register the node.

  1. Configure repositories: 

    yum install -y https://repo.percona.com/yum/percona-release-latest.noarch.rpm

  2. Install the PMM Client package: 

    yum install -y pmm2-client

  3. Check: 

    pmm-admin --version

  4. Register the node.

Package manager – manual download

  1. Visit the Percona Monitoring and Management 2 download page.
  2. Under Version:, select the one you want (usually the latest).
  3. Under Software:, select the item matching your software platform.

  4. Click to download the package file:

    • For Debian, Ubuntu: .deb
    • For Red Hat, CentOS, Oracle Linux: .rpm

(Alternatively, copy the link and use wget to download it.)

Here are the download page links for each supported platform.

dpkg -i *.deb

dnf localinstall *.rpm

Binary package

  1. Download the PMM Client package:

    wget https://downloads.percona.com/downloads/pmm2/2.42.0/binary/tarball/pmm2-client-2.42.0.tar.gz

  2. Download the PMM Client package checksum file:

    wget https://downloads.percona.com/downloads/pmm2/2.42.0/binary/tarball/pmm2-client-2.42.0.tar.gz.sha256sum

  3. Verify the download.

    sha256sum -c pmm2-client-2.42.0.tar.gz.sha256sum

  4. Unpack the package and move into the directory.

    tar xfz pmm2-client-2.42.0.tar.gz && cd pmm2-client-2.42.0

  5. Choose one of these two commands (depends on your permissions):

    Without root permissions

    export PMM_DIR=YOURPATH
    where YOURPATH replace with you real path, where you have required access.

    With root permissions

    export PMM_DIR=/usr/local/percona/pmm2

  6. Run the installer.

    Root permissions (if you skipped step 5 for non root users)

    ./install_tarball

  7. Change the path.

    PATH=$PATH:$PMM_DIR/bin

  8. Set up the agent (pick the command for you depending on permissions)

    Root permissions

    pmm-agent setup --config-file=/usr/local/percona/pmm2/config/pmm-agent.yaml --server-address=192.168.1.123 --server-insecure-tls --server-username=admin --server-password=admin

    Non root users

    pmm-agent setup --config-file=${PMM_DIR}/config/pmm-agent.yaml --server-address=192.168.1.123 --server-insecure-tls --server-username=admin --server-password=admin --paths-tempdir=${PMM_DIR}/tmp --paths-base=${PMM_DIR}

  9. Run the agent.

    pmm-agent --config-file=${PMM_DIR}/config/pmm-agent.yaml

  10. Open a new terminal and check.

    pmm-admin status

    PMM-Agent can be updated from tarball

    1. Download tar.gz with pmm2-client.
    2. Extract it.
    3. Run ./install_tarball script with the “-u” flag.

    The configuration file will be overwritten if you do not provide the “-u” flag while the pmm-agent is updated.

Register

Register your client node with PMM Server.

pmm-admin config --server-insecure-tls --server-url=https://admin:admin@X.X.X.X:443
  • X.X.X.X is the address of your PMM Server.
  • 443 is the default port number.
  • admin/admin is the default PMM username and password. This is the same account you use to log into the PMM user interface, which you had the option to change when first logging in.

Important

Clients must be registered with the PMM Server using a secure channel. If you use http as your server URL, PMM will try to connect via https on port 443. If a TLS connection can’t be established you will get an error and you must use https along with the appropriate secure port.

Examples

Register on PMM Server with IP address 192.168.33.14 using the default admin/admin username and password, a node with IP address 192.168.33.23, type generic, and name mynode.

pmm-admin config --server-insecure-tls --server-url=https://admin:admin@192.168.33.14:443 192.168.33.23 generic mynode

Register your client node running on Docker with PMM Server.

docker exec pmm-admin config --server-insecure-tls --server-url=https://admin:admin@X.X.X.X:443

Add services

You must configure and adding services according to the service type.

Tip

To change the parameters of a previously-added service, remove the service and re-add it with new parameters.

Remove

How to remove (uninstall) PMM Client.

Docker

Caution

These steps delete the PMM Client Docker image and client services configuration data.

  1. Stop pmm-client container.

    docker stop pmm-client

  2. Remove containers.

    docker rm pmm-client

  3. Remove the image.

    docker rmi $(docker images | grep "percona/pmm-client" | awk {'print $3'})

  4. Remove the volume.

    docker volume rm pmm-client-data

Package manager

  1. Uninstall the PMM Client package: 

    apt remove -y pmm2-client

  2. Remove the Percona repository: 

    dpkg -r percona-release

  1. Uninstall the PMM Client package: 

    yum remove -y pmm2-client

  2. Remove the Percona repository: 

    yum remove -y percona-release

Unregister

How to unregister PMM Client from PMM Server.

pmm-admin unregister --force

All services monitored by this node will be removed from monitoring.

Remove services

You must specify the service type and service name to remove services from monitoring.

pmm-admin remove <service-type> <service-name>
service-type
One of mysql, mongodb, postgresql, proxysql, haproxy, external.

See also

Get expert help

If you need assistance, visit the community forum for comprehensive and free database knowledge, or contact our Percona Database Experts for professional support and services.

Community Forum Get a Percona Expert