TiDB Environment and System Configuration Check

This document describes the environment check operations before deploying TiDB. The following steps are ordered by priorities.

Mount the data disk ext4 filesystem with options on the target machines that deploy TiKV

For production deployments, it is recommended to use NVMe SSD of EXT4 filesystem to store TiKV data. This configuration is the best practice, whose reliability, security, and stability have been proven in a large number of online scenarios.

Log in to the target machines using the root user account.

Format your data disks to the ext4 filesystem and add the nodelalloc and noatime mount options to the filesystem. It is required to add the nodelalloc option, or else the TiUP deployment cannot pass the precheck. The noatime option is optional.

Environment Configuration Checklist - 图1

Note

If your data disks have been formatted to ext4 and have added the mount options, you can uninstall it by running the umount /dev/nvme0n1p1 command, skip directly to the fifth step below to edit the /etc/fstab file, and add the options again to the filesystem.

Take the /dev/nvme0n1 data disk as an example:

  1. View the data disk.

    1. fdisk -l
    1. Disk /dev/nvme0n1: 1000 GB

  2. Create the partition.

    1. parted -s -a optimal /dev/nvme0n1 mklabel gpt -- mkpart primary ext4 1 -1

    Environment Configuration Checklist - 图2

    Note

    Use the lsblk command to view the device number of the partition: for a NVMe disk, the generated device number is usually nvme0n1p1; for a regular disk (for example, /dev/sdb), the generated device number is usually sdb1.

  3. Format the data disk to the ext4 filesystem.

    1. mkfs.ext4 /dev/nvme0n1p1

  4. View the partition UUID of the data disk.

    In this example, the UUID of nvme0n1p1 is c51eb23b-195c-4061-92a9-3fad812cc12f.

    1. lsblk -f
    1. NAME    FSTYPE LABEL UUID                                 MOUNTPOINT
    2. sda
    3. ├─sda1  ext4         237b634b-a565-477b-8371-6dff0c41f5ab /boot
    4. ├─sda2  swap         f414c5c0-f823-4bb1-8fdf-e531173a72ed
    5. └─sda3  ext4         547909c1-398d-4696-94c6-03e43e317b60 /
    6. sr0
    7. nvme0n1
    8. └─nvme0n1p1 ext4         c51eb23b-195c-4061-92a9-3fad812cc12f

  5. Edit the /etc/fstab file and add the nodelalloc mount options.

    1. vi /etc/fstab
    1. UUID=c51eb23b-195c-4061-92a9-3fad812cc12f /data1 ext4 defaults,nodelalloc,noatime 0 2

  6. Mount the data disk.

    1. mkdir /data1 && \
    2. mount -a

  7. Check using the following command.

    1. mount -t ext4
    1. /dev/nvme0n1p1 on /data1 type ext4 (rw,noatime,nodelalloc,data=ordered)

    If the filesystem is ext4 and nodelalloc is included in the mount options, you have successfully mount the data disk ext4 filesystem with options on the target machines.

Check and disable system swap

TiDB needs sufficient memory space for operation. When memory is insufficient, using swap as a buffer might degrade performance. Therefore, it is recommended to disable the system swap permanently by executing the following commands:

  1. echo "vm.swappiness = 0">> /etc/sysctl.conf
  2. swapoff -a && swapon -a
  3. sysctl -p

Environment Configuration Checklist - 图3

Note

  • Executing swapoff -a and then swapon -a is to refresh swap by dumping data to memory and cleaning up swap. If you drop the swappiness change and execute only swapoff -a, swap will be enabled again after you restart the system.

  • sysctl -p is to make the configuration effective without restarting the system.

Set temporary spaces for TiDB instances (Recommended)

Some operations in TiDB require writing temporary files to the server, so it is necessary to ensure that the operating system user that runs TiDB has sufficient permissions to read and write to the target directory. If you do not start the TiDB instance with the root privilege, you need to check the directory permissions and set them correctly.

  • TiDB work area

    Operations that consume a significant amount of memory, such as hash table construction and sorting, might write temporary data to disk to reduce memory consumption and improve stability. The disk location for writing is defined by the configuration item tmp-storage-path. With the default configuration, make sure that the user that runs TiDB has read and write permissions to the temporary folder (usually /tmp) of the operating system.

  • Fast Online DDL work area

    When the variable tidb_ddl_enable_fast_reorg is set to ON (the default value in v6.5.0 and later versions), Fast Online DDL is enabled, and some DDL operations need to read and write temporary files in filesystems. The location is defined by the configuration item temp-dir. You need to ensure that the user that runs TiDB has read and write permissions for that directory of the operating system. Taking the default directory /tmp/tidb as an example:

    Environment Configuration Checklist - 图4

    Note

    If DDL operations on large objects exist in your application, it is highly recommended to configure an independent large file system for temp-dir.

    1. sudo mkdir /tmp/tidb

    If the /tmp/tidb directory already exists, make sure the write permission is granted.

    1. sudo chmod -R 777 /tmp/tidb

    Environment Configuration Checklist - 图5

    Note

    If the directory does not exist, TiDB will automatically create it upon startup. If the directory creation fails or TiDB does not have the read and write permissions for that directory, Fast Online DDL might experience unpredictable issues during runtime.

Check and stop the firewall service of target machines

In TiDB clusters, the access ports between nodes must be open to ensure the transmission of information such as read and write requests and data heartbeats. In common online scenarios, the data interaction between the database and the application service and between the database nodes are all made within a secure network. Therefore, if there are no special security requirements, it is recommended to stop the firewall of the target machine. Otherwise, refer to the port usage and add the needed port information to the allowlist of the firewall service.

The rest of this section describes how to stop the firewall service of a target machine.

  1. Check the firewall status. Take CentOS Linux release 7.7.1908 (Core) as an example.

    1. sudo firewall-cmd --state
    2. sudo systemctl status firewalld.service

  2. Stop the firewall service.

    1. sudo systemctl stop firewalld.service

  3. Disable automatic start of the firewall service.

    1. sudo systemctl disable firewalld.service

  4. Check the firewall status.

    1. sudo systemctl status firewalld.service

Check and install the NTP service

TiDB is a distributed database system that requires clock synchronization between nodes to guarantee linear consistency of transactions in the ACID model.

At present, the common solution to clock synchronization is to use the Network Time Protocol (NTP) services. You can use the pool.ntp.org timing service on the Internet, or build your own NTP service in an offline environment.

To check whether the NTP service is installed and whether it synchronizes with the NTP server normally, take the following steps:

  1. Run the following command. If it returns running, then the NTP service is running.

    1. sudo systemctl status ntpd.service
    1. ntpd.service - Network Time Service
    2. Loaded: loaded (/usr/lib/systemd/system/ntpd.service; disabled; vendor preset: disabled)
    3. Active: active (running) since 一 2017-12-18 13:13:19 CST; 3s ago

    • If it returns Unit ntpd.service could not be found., then try the following command to see whether your system is configured to use chronyd instead of ntpd to perform clock synchronization with NTP:

      1. sudo systemctl status chronyd.service
      1. chronyd.service - NTP client/server
      2. Loaded: loaded (/usr/lib/systemd/system/chronyd.service; enabled; vendor preset: enabled)
      3. Active: active (running) since Mon 2021-04-05 09:55:29 EDT; 3 days ago

      If the result shows that neither chronyd nor ntpd is configured, it means that neither of them is installed in your system. You should first install chronyd or ntpd and ensure that it can be automatically started. By default, ntpd is used.

      If your system is configured to use chronyd, proceed to step 3.

  2. Run the ntpstat command to check whether the NTP service synchronizes with the NTP server.

    Environment Configuration Checklist - 图6

    Note

    For the Ubuntu system, you need to install the ntpstat package.

    1. ntpstat

    • If it returns synchronised to NTP server (synchronizing with the NTP server), then the synchronization process is normal.

      1. synchronised to NTP server (85.199.214.101) at stratum 2
      2. time correct to within 91 ms
      3. polling server every 1024 s

    • The following situation indicates the NTP service is not synchronizing normally:

      1. unsynchronised

    • The following situation indicates the NTP service is not running normally:

      1. Unable to talk to NTP daemon. Is it running?

  3. Run the chronyc tracking command to check whether the Chrony service synchronizes with the NTP server.

    Environment Configuration Checklist - 图7

    Note

    This only applies to systems that use Chrony instead of NTPd.

    1. chronyc tracking

    • If the command returns Leap status : Normal, the synchronization process is normal.

      1. Reference ID    : 5EC69F0A (ntp1.time.nl)
      2. Stratum         : 2
      3. Ref time (UTC)  : Thu May 20 15:19:08 2021
      4. System time     : 0.000022151 seconds slow of NTP time
      5. Last offset     : -0.000041040 seconds
      6. RMS offset      : 0.000053422 seconds
      7. Frequency       : 2.286 ppm slow
      8. Residual freq   : -0.000 ppm
      9. Skew            : 0.012 ppm
      10. Root delay      : 0.012706812 seconds
      11. Root dispersion : 0.000430042 seconds
      12. Update interval : 1029.8 seconds
      13. Leap status     : Normal

    • If the command returns the following result, an error occurs in the synchronization:

      1. Leap status    : Not synchronised

    • If the command returns the following result, the chronyd service is not running normally:

      1. 506 Cannot talk to daemon

To make the NTP service start synchronizing as soon as possible, run the following command. Replace pool.ntp.org with your NTP server.

  1. sudo systemctl stop ntpd.service && \
  2. sudo ntpdate pool.ntp.org && \
  3. sudo systemctl start ntpd.service

To install the NTP service manually on the CentOS 7 system, run the following command:

  1. sudo yum install ntp ntpdate && \
  2. sudo systemctl start ntpd.service && \
  3. sudo systemctl enable ntpd.service

Check and configure the optimal parameters of the operating system

For TiDB in the production environment, it is recommended to optimize the operating system configuration in the following ways:

  1. Disable THP (Transparent Huge Pages). The memory access pattern of databases tends to be sparse rather than consecutive. If the high-level memory fragmentation is serious, higher latency will occur when THP pages are allocated.
  2. Set the I/O Scheduler of the storage media to noop. For the high-speed SSD storage media, the kernel’s I/O scheduling operations can cause performance loss. After the Scheduler is set to noop, the performance is better because the kernel directly sends I/O requests to the hardware without other operations. Also, the noop Scheduler is better applicable.
  3. Choose the performance mode for the cpufrequ module which controls the CPU frequency. The performance is maximized when the CPU frequency is fixed at its highest supported operating frequency without dynamic adjustment.

Take the following steps to check the current operating system configuration and configure optimal parameters:

  1. Execute the following command to see whether THP is enabled or disabled:

    1. cat /sys/kernel/mm/transparent_hugepage/enabled
    1. [always] madvise never

    Environment Configuration Checklist - 图8

    Note

    If [always] madvise never is output, THP is enabled. You need to disable it.

  2. Execute the following command to see the I/O Scheduler of the disk where the data directory is located. Assume that you create data directories on both sdb and sdc disks:

    1. cat /sys/block/sd[bc]/queue/scheduler
    1. noop [deadline] cfq
    2. noop [deadline] cfq

    Environment Configuration Checklist - 图9

    Note

    If noop [deadline] cfq is output, the I/O Scheduler for the disk is in the deadline mode. You need to change it to noop.

  3. Execute the following command to see the ID_SERIAL of the disk:

    1. udevadm info --name=/dev/sdb | grep ID_SERIAL
    1. E: ID_SERIAL=36d0946606d79f90025f3e09a0c1f9e81
    2. E: ID_SERIAL_SHORT=6d0946606d79f90025f3e09a0c1f9e81

    Environment Configuration Checklist - 图10

    Note

    If multiple disks are allocated with data directories, you need to execute the above command several times to record the ID_SERIAL of each disk.

  4. Execute the following command to see the power policy of the cpufreq module:

    1. cpupower frequency-info --policy
    1. analyzing CPU 0:
    2. current policy: frequency should be within 1.20 GHz and 3.10 GHz.
    3.               The governor "powersave" may decide which speed to use within this range.

    Environment Configuration Checklist - 图11

    Note

    If The governor "powersave" is output, the power policy of the cpufreq module is powersave. You need to modify it to performance. If you use a virtual machine or a cloud host, the output is usually Unable to determine current policy, and you do not need to change anything.

  5. Configure optimal parameters of the operating system:

    • Method one: Use tuned (Recommended)

      1. Execute the tuned-adm list command to see the tuned profile of the current operating system:

        1. tuned-adm list
        1. Available profiles:
        2. - balanced                    - General non-specialized tuned profile
        3. - desktop                     - Optimize for the desktop use-case
        4. - hpc-compute                 - Optimize for HPC compute workloads
        5. - latency-performance         - Optimize for deterministic performance at the cost of increased power consumption
        6. - network-latency             - Optimize for deterministic performance at the cost of increased power consumption, focused on low latency network performance
        7. - network-throughput          - Optimize for streaming network throughput, generally only necessary on older CPUs or 40G+ networks
        8. - powersave                   - Optimize for low power consumption
        9. - throughput-performance      - Broadly applicable tuning that provides excellent performance across a variety of common server workloads
        10. - virtual-guest               - Optimize for running inside a virtual guest
        11. - virtual-host                - Optimize for running KVM guests
        12. Current active profile: balanced

        The output Current active profile: balanced means that the tuned profile of the current operating system is balanced. It is recommended to optimize the configuration of the operating system based on the current profile.

      2. Create a new tuned profile:

        1. mkdir /etc/tuned/balanced-tidb-optimal/
        2. vi /etc/tuned/balanced-tidb-optimal/tuned.conf
        1. [main]
        2. include=balanced
        4. [cpu]
        5. governor=performance
        7. [vm]
        8. transparent_hugepages=never
        10. [disk]
        11. devices_udev_regex=(ID_SERIAL=36d0946606d79f90025f3e09a0c1fc035)|(ID_SERIAL=36d0946606d79f90025f3e09a0c1f9e81)
        12. elevator=noop

        The output include=balanced means to add the optimization configuration of the operating system to the current balanced profile.

      3. Apply the new tuned profile:

        1. tuned-adm profile balanced-tidb-optimal

    • Method two: Configure using scripts. Skip this method if you already use method one.

      1. Execute the grubby command to see the default kernel version:

        Environment Configuration Checklist - 图12

        Note

        Install the grubby package first before you execute grubby.

        1. grubby --default-kernel
        1. /boot/vmlinuz-3.10.0-957.el7.x86_64

      2. Execute grubby --update-kernel to modify the kernel configuration:

        1. grubby --args="transparent_hugepage=never" --update-kernel /boot/vmlinuz-3.10.0-957.el7.x86_64

        Environment Configuration Checklist - 图13

        Note

        --update-kernel is followed by the actual default kernel version.

      3. Execute grubby --info to see the modified default kernel configuration:

        1. grubby --info /boot/vmlinuz-3.10.0-957.el7.x86_64

        Environment Configuration Checklist - 图14

        Note

        --info is followed by the actual default kernel version.

        1. index=0
        2. kernel=/boot/vmlinuz-3.10.0-957.el7.x86_64
        3. args="ro crashkernel=auto rd.lvm.lv=centos/root rd.lvm.lv=centos/swap rhgb quiet LANG=en_US.UTF-8 transparent_hugepage=never"
        4. root=/dev/mapper/centos-root
        5. initrd=/boot/initramfs-3.10.0-957.el7.x86_64.img
        6. title=CentOS Linux (3.10.0-957.el7.x86_64) 7 (Core)

      4. Modify the current kernel configuration to immediately disable THP:

        1. echo never > /sys/kernel/mm/transparent_hugepage/enabled
        2. echo never > /sys/kernel/mm/transparent_hugepage/defrag

      5. Configure the I/O Scheduler in the udev script:

        1. vi /etc/udev/rules.d/60-tidb-schedulers.rules
        1. ACTION=="add|change", SUBSYSTEM=="block", ENV{ID_SERIAL}=="36d0946606d79f90025f3e09a0c1fc035", ATTR{queue/scheduler}="noop"
        2. ACTION=="add|change", SUBSYSTEM=="block", ENV{ID_SERIAL}=="36d0946606d79f90025f3e09a0c1f9e81", ATTR{queue/scheduler}="noop"

      6. Apply the udev script:

        1. udevadm control --reload-rules
        2. udevadm trigger --type=devices --action=change

      7. Create a service to configure the CPU power policy:

        1. cat  >> /etc/systemd/system/cpupower.service << EOF
        2. [Unit]
        3. Description=CPU performance
        4. [Service]
        5. Type=oneshot
        6. ExecStart=/usr/bin/cpupower frequency-set --governor performance
        7. [Install]
        8. WantedBy=multi-user.target
        9. EOF

      8. Apply the CPU power policy configuration service:

        1. systemctl daemon-reload
        2. systemctl enable cpupower.service
        3. systemctl start cpupower.service

  6. Execute the following command to verify the THP status:

    1. cat /sys/kernel/mm/transparent_hugepage/enabled
    1. always madvise [never]

  7. Execute the following command to verify the I/O Scheduler of the disk where the data directory is located:

    1. cat /sys/block/sd[bc]/queue/scheduler
    1. [noop] deadline cfq
    2. [noop] deadline cfq

  8. Execute the following command to see the power policy of the cpufreq module:

    1. cpupower frequency-info --policy
    1. analyzing CPU 0:
    2. current policy: frequency should be within 1.20 GHz and 3.10 GHz.
    3.               The governor "performance" may decide which speed to use within this range.

  9. Execute the following commands to modify the sysctl parameters:

    1. echo "fs.file-max = 1000000">> /etc/sysctl.conf
    2. echo "net.core.somaxconn = 32768">> /etc/sysctl.conf
    3. echo "net.ipv4.tcp_tw_recycle = 0">> /etc/sysctl.conf
    4. echo "net.ipv4.tcp_syncookies = 0">> /etc/sysctl.conf
    5. echo "vm.overcommit_memory = 1">> /etc/sysctl.conf
    6. echo "vm.min_free_kbytes = 1048576">> /etc/sysctl.conf
    7. sysctl -p

    Environment Configuration Checklist - 图15

    Note

    • vm.min_free_kbytes is a Linux kernel parameter that controls the minimum amount of free memory reserved by the system, measured in KiB.
    • The setting of vm.min_free_kbytes affects the memory reclaim mechanism. Setting it too large reduces the available memory, while setting it too small might cause memory request speeds to exceed background reclaim speeds, leading to memory reclamation and consequent delays in memory allocation.
    • It is recommended to set vm.min_free_kbytes to 1048576 KiB (1 GiB) at least. If NUMA is installed, it is recommended to set it to number of NUMA nodes * 1048576 KiB.
    • For servers with memory sizes less than 16 GiB, it is recommended to keep the default value of vm.min_free_kbytes unchanged.

  10. Execute the following command to configure the user’s limits.conf file:

    1. cat << EOF >>/etc/security/limits.conf
    2. tidb           soft    nofile          1000000
    3. tidb           hard    nofile          1000000
    4. tidb           soft    stack          32768
    5. tidb           hard    stack          32768
    6. EOF

Manually configure the SSH mutual trust and sudo without password

This section describes how to manually configure the SSH mutual trust and sudo without password. It is recommended to use TiUP for deployment, which automatically configure SSH mutual trust and login without password. If you deploy TiDB clusters using TiUP, ignore this section.

  1. Log in to the target machine respectively using the root user account, create the tidb user and set the login password.

    1. useradd tidb && \
    2. passwd tidb

  2. To configure sudo without password, run the following command, and add tidb ALL=(ALL) NOPASSWD: ALL to the end of the file:

    1. visudo
    1. tidb ALL=(ALL) NOPASSWD: ALL

  3. Use the tidb user to log in to the control machine, and run the following command. Replace 10.0.1.1 with the IP of your target machine, and enter the tidb user password of the target machine as prompted. After the command is executed, SSH mutual trust is already created. This applies to other machines as well. Newly created tidb users do not have the .ssh directory. To create such a directory, execute the command that generates the RSA key. To deploy TiDB components on the control machine, configure mutual trust for the control machine and the control machine itself.

    1. ssh-keygen -t rsa
    2. ssh-copy-id -i ~/.ssh/id_rsa.pub 10.0.1.1

  4. Log in to the control machine using the tidb user account, and log in to the IP of the target machine using ssh. If you do not need to enter the password and can successfully log in, then the SSH mutual trust is successfully configured.

    1. ssh 10.0.1.1
    1. [tidb@10.0.1.1 ~]$

  5. After you log in to the target machine using the tidb user, run the following command. If you do not need to enter the password and can switch to the root user, then sudo without password of the tidb user is successfully configured.

    1. sudo -su root
    1. [root@10.0.1.1 tidb]#

Install the numactl tool

This section describes how to install the NUMA tool. In online environments, because the hardware configuration is usually higher than required, to better plan the hardware resources, multiple instances of TiDB or TiKV can be deployed on a single machine. In such scenarios, you can use NUMA tools to prevent the competition for CPU resources which might cause reduced performance.

Environment Configuration Checklist - 图16

Note

  • Binding cores using NUMA is a method to isolate CPU resources and is suitable for deploying multiple instances on highly configured physical machines.
  • After completing deployment using tiup cluster deploy, you can use the exec command to perform cluster level management operations.

To install the NUMA tool, take either of the following two methods:

Method 1: Log in to the target node to install NUMA. Take CentOS Linux release 7.7.1908 (Core) as an example.

  1. sudo yum -y install numactl

Method 2: Install NUMA on an existing cluster in batches by running the tiup cluster exec command.

  1. Follow Deploy a TiDB Cluster Using TiUP to deploy a cluster tidb-test. If you have installed a TiDB cluster, you can skip this step.

    1. tiup cluster deploy tidb-test v6.1.0 ./topology.yaml --user root [-p] [-i /home/root/.ssh/gcp_rsa]

  2. Run the tiup cluster exec command using the sudo privilege to install NUMA on all the target machines in the tidb-test cluster:

    1. tiup cluster exec tidb-test --sudo --command "yum -y install numactl"

    To get help information of the tiup cluster exec command, run the tiup cluster exec --help command.