Installation Issues

Troubleshooting Ideas

The Kato installation process is roughly divided into two stages:

  1. Script initialization phase, responsible for checking the system environment and some preprocessing

  2. During the execution phase of ansible-playbook, the installation task is hosted on ansible

At different stages, the problems encountered and the troubleshooting ideas are different.

Script Initialization Phase

If there is an error in the process, it will be directly checked based on its key fields:

not found *.sh
  • Check whether the specified script is included in the /opt/kato/scripts/installer/ directory. If not, the installation script is incomplete and re-execute the installation.
Not Supported <operating system name>
port <port number> is already used 
The disk is recommended to be at least 40GB
Unable to connect to internet
  • The network connection failed. If it is offline installation, check whether --install-type=offline is specified.
Static binary versions of Kato are available only for 64bit Intel/AMD CPUs (x86_64), but yours is:


Static binary versions of Kato are available only for Linux, but this system is:
Current Node does not exist <specified iip parameter>
  • The specified intranet ip address does not exist on the current server.
The root user must be used by default
  • Should switch to root user installation.
Incomplete parameters of using external database console library

Before performing the installation operation, introduce the specified environment variables into the environment to enable the debugging mode. export DEBUG=true

Ansible-playbook Execution Phase

After entering the ansible-playbook stage, the troubleshooting idea becomes: troubleshooting the error information returned by the playbook.

For example, the error is as follows:

According to the error message:

  • During the execution of the /opt/kato/.init/ script, a non-zero status code is returned.

Troubleshooting operations you can try:

  • Read the script /opt/kato/.init/ to understand its working content.

In fact, the purpose of the current script is to initialize the cluster database rbd-db service (or an external database specified by the user). This problem is prone to occur when the server memory is insufficient or the disk performance is low. The specific solution is to manually initialize the database after the installation process is over

If you want to know the detailed information of the task, you can find the file that defines the task in the following corresponding way

Task TASK [node/init: init kato] corresponds to the task named init kato in /opt/kato/kato-ansible/roles/node/init/tasks/main.yml

- name: init kato 
  shell: "bash /opt/kato/.init/> /tmp/install/init.r6d.log"
  register: init_r6d_ok
  until: init_r6d_ok is succeeded
  retries: 5
  ignore_errors: true

It is impossible to list all the reasons for the failure of the task. However, after the execution of most tasks fails, the starting point for troubleshooting can be found through the prompt of msg information.

Interpretation of KATO cluster installation and operation and maintenance principles

My Question is not Covered

If you are still at a loss as to how to troubleshoot and solve your installation problems after reading this document, you can:

  • Go to GitHub to check whether there are related issues, and if not, submit issues

  • Go to Community to read the post with the prefix [Installation Question] to find answers to similar questions