Common issues about DBGateway - Database Autonomy Service

This topic describes the directory structure of DBGateway and basic operations that can be performed on DBGateway, and shows how to troubleshoot common issues that you may encounter when you use DBGateway.

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 about DBGateway. 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.

Basic operations

View the logs of DBGateway
- The log files of DBGateway are stored in the /opt/dbgateway/log/dbgateway.log path.
- Log files are text files. You can use standard UNIX utilities such as vim, tail, cat, and less to view the log files.
The customer service or technical support personnel of Database Autonomy Service (DAS) may require the logs of DBGateway for troubleshooting. In this case, you can log on to the server on which DBGateway is deployed and run the following command to view the last 200 log entries. Then, you must copy and send the log entries to the customer service or technical support personnel for troubleshooting.
```
tail -n 200 /opt/dbgateway/log/dbgateway.log
```
Check whether a DBGateway process is running
1. Log on to the DAS console.
2. In the left-side navigation pane, click DBGateways.
3. On the DBGateways page, find the DBGateway process that you want to manage and view the information displayed in the Current Status column.
  If Normal is displayed in the Current Status column, the DBGateway process is running. If Abnormal is displayed, run the following command on the server on which DBGateway is deployed:
```
/opt/dbgateway/bin/dbgateway-manager -d status
```
  - If the DBGateway process is running, the following output is returned:
```
DBGateway is running.
```
  - If the DBGateway process is not alive, the following output is returned:
```
DBGateway is dead.
```
  Note
  The preceding operations can be performed to check whether a DBGateway process is running but cannot be used to check whether the DBGateway process is running as expected.
Restart a DBGateway process
1. Before you restart a DBGateway process, you must check the state of the DBGateway process by performing the operations provided in the "Check whether a DBGateway process is running" section of this topic.
2. Restart the DBGateway process.
  - If the DBGateway process is running, perform the following operations:
    - On the DBGateways page, find the DBGateway process that you want to restart and choose Manage > Restart in the Actions column.
    - Run the following command on the server on which DBGateway is deployed:
```
/opt/dbgateway/bin/dbgateway-manager -d restart
```
  - If the DBGateway process is not alive, perform the following operations:
    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 on which DBGateway is deployed: Run the following command on the server on which DBGateway is deployed:
```
/opt/dbgateway/bin/dbgateway-manager -d restart
```
Upgrade a DBGateway process
On the DBGateways page, find the DBGateway process that you want to upgrade and choose Manage > Upgrade in the Actions column.
Stop a DBGateway process
- On the DBGateways page, find the DBGateway process that you want to stop and choose Manage > Stop in the Actions column.
- Run the following command on the server on which DBGateway is deployed:
```
 /opt/dbgateway/bin/dbgateway-manager -d stop
```
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 the process.
1. On the DBGateways page, find the DBGateway process that you want to delete and choose Manage > Delete in the Actions column.
2. Optional. Run the following command on the server on which DBGateway is deployed to delete the installation directory of DBGateway:
```
rm -rf /opt/dbgateway
```
Redeploy a DBGateway
After a DBGateway is deleted, you can run the deployment commands that are obtained by the DAS console when the DBGateway is connected to the database instance to redeploy the DBGateway on the destination server.

Deployment issue troubleshooting

If a database gateway in centralized mode or a database gateway in host mode is connected to a database instance, you can obtain commands that are used to deploy DBGateway. In this section, the command shown in the following figure is run as an example. Replace the vpcID and token values in the command with the actual values in use.

The DBGateway deployment scripts cannot be downloaded.
- If the wget command not found error message is returned, the wget command is unavailable. Run one of the following commands to install the wget utility:
```
sudo apt-get install wget
```
  or
```
yum -y install wget
```
- Check whether the server is connected to Alibaba Cloud 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 command, the OSS domain name is hdm-dbgateway-cn-hangzhou.oss-cn-hangzhou.aliyuncs.com. Replace the domain name with the actual domain name in use.
```
ping hdm-dbgateway-cn-hangzhou.oss-cn-hangzhou.aliyuncs.com
```
  - If the following output is returned, the domain name cannot be resolved. Check whether your DNS server settings are correct and whether the domain name resolution service works as expected.
```
ping: unknown host hdm-dbgateway-cn-hangzhou.oss-cn-hangzhou.aliyuncs.com  
```
  - If no output is returned for an extended period of time after you run the ping command, the network connection fails. In this case, perform the following operations:
    - Check whether the network configurations of the server are correct.
    - Check whether the server is connected over the Internet or a VPC.
    - Check whether the specified region is correct if the server is connected over a VPC.
Check whether the server is connected to the DAS server.
Run the following command on the server on which DBGateway needs to be deployed. In the following command, the domain name of the DAS server is master-hdm-cn-hangzhou.aliyuncs.com. Replace the domain name with the actual domain name in use.
```
telnet master-hdm-cn-hangzhou.aliyuncs.com 80
```
- If the Name or service not known error message is returned, the domain name cannot be resolved. In this case, check whether your DNS server settings are correct and whether the domain name resolution service works as expected.
- If the Trying 10.0.XX.XX message is returned, the network connection fails. In this case, perform the following operations:
  - Check whether the network configurations of the server are correct.
  - Check whether the server is connected over the Internet or a VPC.
  - Check whether the specified region is correct if the server is connected over a VPC.
- If the following output is returned, the server is connected to the DAS server:
```
Connected to master-hdm-cn-hangzhou.aliyuncs.com.  Escape character is '^]'.
```
  If DBGateway still fails to start up, follow the instructions in the "View the logs of DBGateway" section of this topic for troubleshooting.

Operation issue troubleshooting

Authentication failures or insufficient permissions
- Check whether the authorized account with the specified password has the following permissions. In the following examples, the das_test account is used.
  - MySQL
```
CREATE USER 'das_test'@'%' IDENTIFIED BY 'password';
GRANT SHOW DATABASES, PROCESS, REPLICATION SLAVE, REPLICATION CLIENT ON *.* TO 'das_test'@'%';
GRANT SELECT ON *.*  TO 'das_test'@'%';
```
  - PostgreSQL
```
CREATE USER das_test PASSWORD 'password';
GRANT SELECT ON ALL TABLES IN SCHEMA PUBLIC TO das_test;
/* Optional. Collect slow query logs and SQL statements. */ 
ALTER USER das_test WITH SUPERUSER;
```
  - MongoDB
```
use admin;
db.createUser({user:'das_test',pwd:'password',roles:[{role:'readAnyDatabase', db:'admin'}, {role:'clusterMonitor', db:'admin'}, {role: 'hostManager', db: 'admin'}]})
```
    If the (Unauthorized) not authorized on admin to execute command error message is returned, run the following command to grant the required permissions to the das_test account:
```
db.grantRolesToUser("das_test", [{db: "local", role: "dbAdmin"},{db: "config", role: "dbAdmin"},{db: "admin", role: "dbAdminAnyDatabase"}])
```
  - Redis
    You do not need to create Redis accounts to use the Redis service. You need to only 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 on which DBGateway is deployed 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 DBGateway to the latest version.
Connection failures
A connection 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 does not run as expected, check whether the process of the database instance exists. The database instance can be a MySQL, PostgreSQL, MongoDB, or Redis instance.
- Check whether the server on which DBGateway is deployed is connected to the database instance. The database instance can be a MySQL, PostgreSQL, MongoDB, or Redis 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.XX.XX 3306
```
  - If the following output is returned, the network connection is normal. You must follow the instructions in the "View the logs of DBGateway" section of this topic for troubleshooting.
```
Connected to 192.168.XX.XX
Escape character is '^]'.
```
  - If the preceding output is not returned, a connectivity issue occurs. This issue is typically caused due to the following reasons: networks are isolated among servers, the route settings are invalid, and the firewall or database instance denies remote access requests.
Abnormal monitoring status
- Check the running state of a DBGateway process.
- Restart the DBGateway process and check whether the monitoring feature recovers from the exceptions.
- We recommend that you upgrade DBGateway to the latest version.
The Authorized. Verifying message that remains for a long time
In most cases, the state 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 operations:
- Check the running state of a DBGateway process.
- Restart the DBGateway process and check whether the database instance is connected as expected.
- We recommend that you upgrade DBGateway to the latest version.