This topic describes how to troubleshoot common issues you may encounter when you use DBGateway.

Overview and basic operations

  1. Directory structure:
    dbgateway
    |-- bin
    |   |-- dbgateway
    |   \-- dbgateway-manager
    |-- conf
    |   |-- dbgateway.conf
    |   \-- server.crt
    \-- log
        |-- dbgateway.err
        |-- dbgateway.log
        \-- dbgateway_manager.log    
    Note
    • The bin folder contains the dbgateway and dbgateway-manager files. The dbgateway file is the main program. The dbgateway-manager file stores management scripts that are used to maintain DBGateway.
    • The conf folder contains the dbgateway.conf and server.crt files. The dbgateway.conf file stores the configuration information. The server.crt file stores the public key certificate.
    • The log folder contains the dbgateway.err, dbgateway.log, and dbgateway_manager.log files. The dbgateway.err file stores the error messages of DBGateway. The dbgateway.log file stores the logs of DBGateway. The dbgateway_manager.log file stores the logs of DBGateway management scripts.
  2. View the logs of DBGateway

    The full path to the log file of DBGateway is "/opt/dbgateway/log/dbgateway.log".

    The log file is a text file. You can use standard Unix utilities such as vim, tail, cat, and less to view the log file.

    The customer service or technical support personnel of DAS may require the logs of DBGateway for troubleshooting. In this scenario, you can run the following command to view the last 200 log entries. Then, you need to copy and send the log entries to the customer service or technical support personnel for troubleshooting.

    tail -n 200 /opt/dbgateway/log/dbgateway.log
  3. Check whether a DBGateway process is alive
    1. In the left-side navigation pane of the DAS console, click DBGateways. On the page that appears, check whether a DBGateway process is in the Normal state. If yes, the DBGateway process is alive.
    2. If not, run the following command on the server where DBGateway is deployed for further troubleshooting:
      /opt/dbgateway/bin/dbgateway-manager -d status
      Note You can perform the preceding operations to check whether a DBGateway process is alive. However, you cannot perform these operations to check whether the DBGateway process is running as expected.

      The following sample response is returned if the DBGateway process is alive:

      DBGateway is running.

      The following sample response is returned if the DBGateway process is not alive:

      DBGateway is dead.
  4. Restart a DBGateway process
    Note Before you restart a DBGateway process, you must check the status of the DBGateway process by performing the operations provided in the "Check whether a DBGateway process is alive" section of this topic.
    • The DBGateway process is alive.
      1. You can restart a DBGateway process in the DAS console. In the left-side navigation pane of the DAS console, click DBGateways. On the page that appears, find the DBGateway process that you want to restart and choose Manage > Restart.

      2. You can also restart a DBGateway process by running the following command on the server where DBGateway is deployed:
         /opt/dbgateway/bin/dbgateway-manager -d restart
    • The DBGateway process is not alive.

      If the DBGateway process is not alive, you cannot restart the DBGateway process in the DAS console. You can restart the DBGateway process only by running the following command on the server where DBGateway is deployed:

       /opt/dbgateway/bin/dbgateway-manager -d restart
  5. Upgrade a DBGateway process

    In the left-side navigation pane of the DAS console, click DBGateways. On the page that appears, find the DBGateway progress that you want to upgrade and choose Manage > Upgrade.

  6. Stop a DBGateway process
    • You can stop a DBGateway process in the DAS console. In the left-side navigation pane of the DAS console, click DBGateways. On the page that appears, find the DBGateway progress that you want to stop and choose Manage > Stop.

    • You can also stop a DBGateway process by running the following command on the server where DBGateway is deployed:
       /opt/dbgateway/bin/dbgateway-manager -d stop
  7. Delete a DBGateway process
    Note
    • After a DBGateway process is deleted, all DAS features of the database instances that are associated with the DBGateway process become unavailable.
    • If a DBGateway process is in the Normal state, you must stop the DBGateway process before you delete it. To stop the DBGateway process, perform the operations provided in the "Stop a DBGateway process" section of this topic.
    1. You can delete a DBGateway process in the DAS console. In the left-side navigation pane of the DAS console, click DBGateways. On the page that appears, find the DBGateway process that you want to delete and choose Manage > Delete.
    2. (Optional) You can delete a DBGateway process by running the following command on the server where DBGateway is deployed to delete the installation directory of DBGateway:
      rm -rf /opt/dbgateway

Deployment issue troubleshooting

The DAS console provides a deployment command of DBGateway. In the following command, the VPC ID and the token are used only as examples. You must substitute the VPC ID and the token with the actual values.

  • The DBGateway deployment scripts cannot be downloaded.
    Troubleshoot the issue based on the following possible causes:
    • Check whether the wget command exists on the current system. If the following message appears, the wget command does not exist.
      wget command not found

      wget is a Linux command line utility that you can use to download files. If the wget command is not found, you can use the following method to install the wget utility:

      sudo apt-get install wget

      You can also use the following method to install the wget utility:

      yum -y install wget
    • Check whether the server is connected to Object Storage Service (OSS).

      Obtain the OSS domain name, and run the following ping command to check whether the server is connected to OSS. In the following example, the OSS domain name is hdm-dbgateway-cn-hangzhou.oss-cn-hangzhou.aliyuncs.com. Replace the domain name with the actual one that is included in your deployment command.

      ping hdm-dbgateway-cn-hangzhou.oss-cn-hangzhou.aliyuncs.com
      • If the domain name cannot be resolved, check whether your DNS server settings are correct and whether the domain name resolution service runs as expected.
        ping: unknown host hdm-dbgateway-cn-hangzhou.oss-cn-hangzhou.aliyuncs.com  
        # The "unknown host" message indicates that the domain name cannot be resolved.
      • If you fail to receive a response for a long period of time after you run the ping command, the network connection fails. In this scenario, perform the following operations:
        • Check whether the network configurations of the server are correct.
        • Check whether the network of the server is a VPC or the classic network. In the DNS console, select the correct network type for the server.
        • Check whether you select the correct region where the VPC is deployed. For example, you can select the China (Beijing), China (Shanghai), or China (Shenzhen) region in the console.
  • HDM-Master is not connected to DBGateway as expected.

    In this example, the domain name of the HDM-Master service is master-hdm-cn-hangzhou.aliyuncs.com. Replace the domain name with the actual one that is included in your deployment command. Perform the following operation for troubleshooting:

    Run the following command on the server where DBGateway is deployed:

    telnet master-hdm-cn-hangzhou.aliyuncs.com 80
    • If the "Name or service not known" message is returned, the domain name cannot be resolved. In this scenario, check whether your DNS server settings are correct and whether the domain name resolution service runs as expected.
    • If the Trying xxx.xxx.xxx.xxx… message is returned, the network is interrupted. In this scenario, perform the following operations to check the connectivity:
      • Check whether the network configurations of the server are correct.
      • Check whether the network of the server is a VPC or the classic network. In the DNS console, select the correct network type for the server.
      • Check whether you select the correct region where the VPC is deployed. For example, you can select the China (Beijing), China (Shanghai), or China (Shenzhen) region in the console.
    • If the following message is returned, HDM-Master is connected.
        Connected to master-hdm-cn-hangzhou.aliyuncs.com.  Escape character is '^]'.

      If DBGateway still fails to start, follow the instructions in the "View the logs of DBGateway" section for troubleshooting.

Operation issue troubleshooting

  • Authentication fails or permissions are insufficient.

    Troubleshoot the issue based on the following possible causes:

    • Check whether the authorized account with the specified password has the following permissions:
      • MySQL:
        SHOW DATABASES, PROCESS, REPLICATION SLAVE, REPLICATION CLIENT ON *. *  
        SELECT ON mysql. *  
        SELECT ON performance_schema. *
      • MongoDB:
        Permissions of a database administrator and the root user
      • You do not need to create Redis accounts to use the Redis service. You need only to make sure that the password is valid to access the Redis service.

        To change the password that is used to access the Redis service, modify the requirepass setting in the configuration file and restart the Redis service. For more information, see Redis configuration.

    • Check whether the authorized account and the password are valid. We recommend that you initiate a remote connection request from the server and use the authorized account and the password to connect to the database instance.
    • Restart a DBGateway process and check whether the database instance is connected as expected.
    • We recommend that you upgrade the DBGateway process to the latest version.
  • The database instance fails to be connected.

    A connectivity failure occurs because DBGateway cannot connect to a database instance. Troubleshoot the issue based on the following possible causes:

    • Check whether the database instance runs as expected.

      If the database instance is not running as expected, check whether the process of the database instance exists. The database instance can be a MySQL, MongoDB, or Redis instance.

    • Check whether the server where DBGateway is deployed is connected to the database instance.

      To perform the checks, run the following command:

      telnet <IP address or domain name of the database instance> <Service port number of the database instance>  
      Example: telnet 192.168.100.1 3306.

      The following message indicates that the network connection is normal. In this scenario, follow the instructions in the "View the logs of DBGateway" section of this topic for troubleshooting.

      Connected to xxxxxx.
      Escape character is '^]'.

      If the message does not appear, a connectivity issue exists. In most cases, the possible causes include that networks are isolated among servers and that the route settings are invalid. Another possible cause is that the firewall or the database instance denies remote access requests.

  • Monitoring exceptions occur.
    • Check the status of the DBGateway process by performing the operations provided in the "Check whether a DBGateway process is alive" section of this topic.
    • Restart the DBGateway process and check whether the monitoring feature recovers from the exceptions.
    • We recommend that you upgrade the DBGateway process to the latest version.
  • "Authorized. Verifying" remains for more than two minutes.

    In most cases, the status of the instance changes to Accessed within one to two minutes after the authorization is successful. However, if the Authorized. Verifying message remains for more than two minutes, perform the following steps:

    • Check the status of the DBGateway process by performing the operations provided in the "Check whether a DBGateway process is alive" section of this topic.
    • Restart the DBGateway process and check whether the database instance is connected as expected.
    • We recommend that you upgrade the DBGateway process to the latest version.