Skip to content
logo
Percona Monitoring and Management
Client
Initializing search
    percona/pmm-doc
    percona/pmm-doc
    • Welcome
    • Setting up
      • Server
        • Network
        • Docker
        • Podman
        • Helm
        • Virtual Appliance
        • AWS Marketplace
        • Easy-install script
      • Client
        • MySQL
        • MongoDB
        • PostgreSQL
        • ProxySQL
        • Amazon RDS
        • Microsoft Azure
        • Google Cloud Platform
        • Linux
        • External Services
        • HAProxy
        • Remote instances
    • Get started
      • User Interface
      • Percona Alerting
      • Backup and Restore
        • Prepare a storage location
        • MongoDB backups
          • MongoDB backup prerequisites
          • Create MongoDB on-demand and scheduled backups
          • Create MongoDB PITR backups
          • Restore a MongoDB backup
          • MongoDB Backup and Restore support matrix
        • MySQL backups
          • MySQL backup prerequisites
          • Create a MySQL backup
          • Restore a MySQL backup
        • Edit a scheduled backup
        • Delete a backup
      • Roles and permissions
        • Configure access control
        • Labels for access control
        • Create access roles
        • Manage access roles
        • Assign roles to users
        • Use Case
      • Query Analytics
      • Working with Advisors
    • How to
      • Configure
      • Manage users
      • Upgrade
      • Secure
      • Optimize
      • Annotate
      • Share dashboards and panels
      • Extend Metrics
      • Resolve issues
      • Integrate with Percona Platform
        • Check Percona Portal account information
    • Details
      • Architecture
      • UI components
      • PMM components and versions
      • Data handling in PMM
      • Develop Advisor checks
      • PMM Inventory
      • Dashboards
        • Manage dashboards
          • Insight
            • Advanced Data Exploration
            • VictoriaMetrics
            • VictoriaMetrics Agents Overview
          • Environments
            • Environment Summary
          • Kubernetes
            • Kubernetes Pods Status
            • Kubernetes Volumes
          • DBaas
          • OS Dashboards
            • Disk Details
            • Network Details
            • Memory Details
            • Node Temperature Details
            • Nodes Compare
            • Nodes Overview
            • Node Summary
            • NUMA Details
            • Processes Details
          • Prometheus Dashboards
            • Prometheus Exporters Overview
          • MySQL Dashboards
            • MySQL Command/Handler Counters Compare
            • MySQL InnoDB Compression Details
            • MySQL InnoDB Details
            • MySQL MyISAM/Aria Details
            • MySQL MyRocks Details
            • MySQL Instance Summary
            • MySQL Instances Compare
            • MySQL Instances Overview
            • MySQL Wait Event Analyses Details
            • MySQL Performance Schema Details
            • MySQL Query Response Time Details
            • MySQL Replication Summary
            • MySQL Group Replication Summary
            • MySQL Table Details
            • MySQL User Details
            • MySQL TokuDB Details
          • MongoDB Dashboards
            • Experimental MongoDB Collection Details
            • Experimental MongoDB Oplog Details
            • MongoDB Cluster Summary
            • MongoDB Instance Summary
            • MongoDB Instances Overview
            • MongoDB Instances Compare
            • MongoDB ReplSet Summary
            • MongoDB InMemory Details
            • MongoDB MMAPv1 Details
            • MongoDB WiredTiger Details
          • PostgreSQL Dashboards
            • PostgreSQL Instance Summary
            • PostgreSQL Instances Compare
            • Experimental PostgreSQL Vacuum Monitoring
          • ProxySQL Dashboards
          • HA Dashboards
            • PXC/Galera Cluster Summary
            • Experimental PXC/Galera Cluster Summary
            • PXC/Galera Nodes Compare
            • HAProxy Instance Summary
      • Commands
        • pmm-admin - PMM Administration Tool
        • pmm-agent - PMM Client agent
      • API
      • VictoriaMetrics
      • ClickHouse
      • PostgreSQL
      • Glossary
      • Introduction
      • DBaaS architecture
        • Setting up DBaaS
        • Create a Kubernetes Cluster
        • Deleting Kubernetes clusters
        • Activating DBaaS
        • Add a Kubernetes cluster automatically
        • Add a Kubernetes cluster manually
        • Manage allowed component versions
          • OLM installation
          • Operators installation
        • Add a DB Cluster
        • Manage a DB Cluster
        • Delete a DB Cluster
        • Create a database cluster from a template
      • Backup and restore
    • FAQ
    • Release Notes
      • PMM 2.39.0
      • PMM 2.38.1
      • PMM 2.38.0
      • PMM 2.37.1
      • PMM 2.37.0
      • PMM 2.36.0
      • PMM 2.35.0
      • PMM 2.34.0
      • PMM 2.33.0
      • PMM 2.32.0
      • PMM 2.31.0
      • PMM 2.30.0
      • PMM 2.29.1
      • PMM 2.29.0
      • PMM 2.28.0
      • PMM 2.27.0
      • PMM 2.26.0
      • PMM 2.25.0
      • PMM 2.24.0
      • PMM 2.23.0
      • PMM 2.22.0
      • PMM 2.21.0
      • PMM 2.20.0
      • PMM 2.19.0
      • PMM 2.18.0
      • PMM 2.17.0
      • PMM 2.16.0
      • PMM 2.15.1
      • PMM 2.15.0
      • PMM 2.14.0
      • PMM 2.13.0
      • PMM 2.12.0
      • PMM 2.11.1
      • PMM 2.11.0
      • PMM 2.10.1
      • PMM 2.10.0
      • PMM 2.9.1
      • PMM 2.9.0
      • PMM 2.8.0
      • PMM 2.7.0
      • PMM 2.6.1
      • PMM 2.6.0
      • PMM 2.5.0
      • PMM 2.4.0
      • PMM 2.3.0
      • PMM 2.2.2
      • PMM 2.2.1
      • PMM 2.2.0
      • PMM 2.1.0
      • PMM 2.0.1
      • PMM 2.0.0
      • Copyright and licensing information
      • Trademark policy

    • Before you start
    • Install
      • Docker
      • Package manager
        • Debian-based
        • Red Hat-based
      • Package manager -- manual download
        • Debian-based
        • Red Hat-based
      • Binary package
    • Register
      • Examples
    • Add services
    • Remove
      • Docker
      • Package manager
        • Debian-based distributions
        • Red Hat-based distributions
    • Unregister
    • Remove services

    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:

    • Register the node with PMM Server.
    • Configure and add services according to type.

    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.

    1. 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
    

    Debian-based¶

    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.

      Root permissions

      apt update
      apt install -y pmm2-client
      
    3. Check.

      pmm-admin --version
      
    4. Register the node.

    Red Hat-based¶

    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.

    • Debian 9 (Stretch)
    • Debian 10 (Buster)
    • Debian 11 (Bullseye)
    • Red Hat/CentOS/Oracle 7
    • Red Hat/CentOS/Oracle 8
    • Ubuntu 18.04 (Bionic Beaver)
    • Ubuntu 20.04 (Focal Fossa)
    • Ubuntu 22.04 (Jammy Jellyfish)

    Debian-based¶

    dpkg -i *.deb
    

    Red Hat-based¶

    dnf localinstall *.rpm
    

    Binary package¶

    1. Download the PMM Client package:

      wget https://downloads.percona.com/downloads/pmm2/2.39.0/binary/tarball/pmm2-client-2.39.0.tar.gz
      
    2. Download the PMM Client package checksum file:

      wget https://downloads.percona.com/downloads/pmm2/2.39.0/binary/tarball/pmm2-client-2.39.0.tar.gz.sha256sum
      
    3. Verify the download.

      sha256sum -c pmm2-client-2.39.0.tar.gz.sha256sum
      
    4. Unpack the package and move into the directory.

      tar xfz pmm2-client-2.39.0.tar.gz && cd pmm2-client-2.39.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
      

      !!! hint 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
    

    Add services¶

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

    • MySQL (and variants Percona Server for MySQL, Percona XtraDB Cluster, MariaDB)
    • MongoDB
    • PostgreSQL
    • ProxySQL
    • Amazon RDS
    • Microsoft Azure
    • Google Cloud Platform (MySQL and PostgreSQL)
    • Linux
    • External services
    • HAProxy
    • Remote instances

    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¶

    Debian-based distributions¶

    1. Uninstall the PMM Client package.

      apt remove -y pmm2-client
      
    2. Remove the Percona repository

      dpkg -r percona-release
      

    Red Hat-based distributions¶

    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

    • Percona release
    • PMM Client architecture

    Contact us

    For free technical help, visit the Percona Community Forum.

    To report bugs or submit feature requests, open a JIRA ticket.

    For paid support and managed or consulting services , contact Percona Sales.


    Last update: 2023-09-27
    Percona LLC, © 2023
    Made with Material for MkDocs

    Cookie consent

    We use cookies to recognize your repeated visits and preferences, as well as to measure the effectiveness of our documentation and whether users find what they're searching for. With your consent, you're helping us to make our documentation better. Read more about Percona Cookie Policy.