Deploy ODP by using the CLI|V4.0.0|OceanBase Database Proxy| docs|Distributed Database

OceanBase Database Proxy (ODP) can forward data access requests of users to correct OBServers. The results are returned to the clients by using ODP. This topic describes how to install ODP by using the ODP RPM Package Manager (RPM) package.

You can also install and deploy ODP by using OceanBase Cloud Platform (OCP). For more information, see Create an OBProxy cluster.

Notice

After you deploy ODP on a server, ODP provides the proxy service of OceanBase Database by exposing a socket in the format of IP address:Port number. You can access OceanBase Database by using the socket in the same way you access MySQL databases. We recommend that you deploy ODP on an OBServer.

We recommend that you deploy only one ODP on a server and use Port 2883. If you deploy multiple ODPs on the same server, you need to specify different ports and configuration file paths for differentiation. You can set the port number to 3306, 1521, or other numbers.

The sample IP addresses in this topic are desensitized. You must specify the actual IP addresses of your servers.

Environment preparations

Platform: x86_64 or ARM
Operating system: Linux Red Hat ((x86_64) of version 5, 6, 7, or later
CPU: ODP occupies about 70% of the resources of a CPU core during operation.
Memory: ODP occupies about 100 MB of memory during operation.
Disk space: The disk space is determined by your data size. We recommend that you use a disk that has 10 GB or more of space.
OceanBase cluster: For more information, see Deploy an OceanBase cluster.

Install ODP

Run the following command as the root user to add the write privilege on the sudoers file:

# Add the write privilege on the sudoers file.
chmod u+w /etc/sudoers
echo 'admin ALL=(ALL) NOPASSWD: ALL' >> /etc/sudoers

# Revoke the write privilege on the sudoers file.
chmod u-w /etc/sudoers

Run the following command to install the ODP RPM package:
```
-bash-4.2$ cd $rpm_dir
-bash-4.2$ sudo rpm -ivh $rpm_name
```
$rpm_dir specifies the directory in which the RPM package is stored. $rpm_name specifies the name of the RPM package.
Note
- You can obtain the latest RPM package for ODP from OceanBase Technical Support.
- ODP is installed in the /opt/taobao/install directory.
Example:
```
-bash-4.2$ sudo rpm -ivh obproxy-4.0.0-20221103165243.el7.x86_64.rpm
Preparing...                          ################################# [100%]
Updating / installing...
   1:obproxy-4.0.0-20221103165243.el7 ################################# [100%]
```

(Optional) Create soft links to ODP:

A soft link to ODP can hide the version information, facilitating subsequent operations.

ODP is installed in the /opt/taobao/install directory. The home directory of the ODP process is /opt/taobao/install/obproxy, which is a soft link that points to the directory of ODP of the corresponding version.

-bash-4.2$ cd /opt/taobao/install
-bash-4.2$ sudo ln -s obproxy-4.0.0 obproxy
-bash-4.2$ ll
total 8
drwxr-xr-x 9 root  root  4096 Sep 26 15:24 ajdk-8.3.6-b129
lrwxrwxrwx 1 root  root    13 Nov 14 12:03 obproxy -> obproxy-4.0.0
drwxr-xr-x 4 admin admin 4096 Nov 14 11:59 obproxy-4.0.0

# Change the owner and group of the ODP process to admin.
-bash-4.2$ sudo chown -R admin:admin obproxy
-bash-4.2$ ll
total 8
drwxr-xr-x 9 root  root  4096 Sep 26 15:24 ajdk-8.3.6-b129
lrwxrwxrwx 1 admin admin   13 Nov 14 12:03 obproxy -> obproxy-4.0.0
drwxr-xr-x 4 admin admin 4096 Nov 14 11:59 obproxy-4.0.0

Initialize ODP

ODP needs to communicate with the backend OBServer node. Therefore, you must create the proxyro user and specify the password for ODP in the sys tenant of the OceanBase cluster. If you start ODP later, you can specify the username and password of the proxyro user in the startup parameters.

Note

ODP uses the proxyro user to access the OceanBase cluster. One proxyro user can be used for accessing one OceanBase cluster.

To check whether a proxyro user exists in the cluster, perform the following steps:

Log on to the cluster by creating an IP address-based direct connection.
```
obclient -h10.10.10.1 -uroot@sys -P2881 -p
```
Run the following command to query the users in the sys tenant:
```
obclient> select user,password from mysql.user;
```
If the output shows that a proxyro user already exists, you can directly start ODP. If the output shows that no proxyro user exists, run the command to create one.

Create a proxyro user.

Example:

$ obclient -h10.10.10.1 -uroot@sys -P2881 -p -c -A

obclient> CREATE USER proxyro IDENTIFIED BY '******';
Query OK, 0 rows affected

obclient> GRANT SELECT ON *.* TO proxyro;
Query OK, 0 rows affected

obclient> SHOW GRANTS FOR proxyro;
+----------------------------------+
| Grants for proxyro@%             |
+----------------------------------+
| GRANT SELECT ON *.* TO 'proxyro' |
+----------------------------------+
1 row in set

Start ODP

You can use either of the following methods to start an ODP process:

Specify the -r parameter in the startup command to specify the information of the RootServer in the OceanBase cluster.

This method does not require other configurations, and is usually used in the development and debugging phase.
Specify the obproxy_config_server_url parameter in the startup command to obtain the information of the RootServer in the OceanBase cluster.

This method requires the obproxy_config_server_url parameter, thus relying on the startup of the Config Server. We recommend that you use this method to start an ODP.

Notice

To start the ODP, log on as the admin user and run the startup command in the home directory of the ODP software. The ODP startup fails if you log on as other users or run the startup command in other directories.

Procedure

Log on as the admin user to the server that hosts the ODP to be started.
Run the following command in the directory where the ODP is installed to start the ODP.

Note

Before you start the ODP, you can run the ./bin/obproxy -h command to query the startup parameters of the ODP.
1. Run the following command to specify the -r option in the startup command:
```
./bin/obproxy -p <obproxy_port> -r <'ip:port'> -n <appname> -o -c <cluster_name>
```
  Parameters:
  - -p: specifies the port number listened to by ODP. The MySQL client uses this port to access OceanBase Database. The parameter is required for the first startup. You do not need to specify this parameter in subsequent startups or upgrades.
  - -r: specifies the IP address and port number of the RootServer in the specified OceanBase cluster. The port is the SQL Port of the OBServer, not the RPC Port.
  - -n: specifies the application name of the ODP to be started. This parameter is optional.
    
    You can use the app_name parameter to change the application name of the ODP. The default value is undefined.
  - -o: specifies the hardware or kernel parameter settings. If you do not specify this parameter, the default system configurations are used.
  - -c: specifies the OceanBase cluster.
  Example:
```
[admin@001 ~]$ ./bin/obproxy -p 2883 -r'10.10.10.1:2881;10.10.10.2:2881;10.10.10.3:2881' -o "observer_sys_password=$sha1_value,obproxy_sys_password=$sha1_value,enable_cluster_checkout=false" -n test -c mycluster
```
  Notice
  - observer_sys_password must be the password of the proxyro user of OceanBase Database. obproxy_sys_password is the password of the root@proxysys account for logging on to the ODP.
  - Replace the password in $sha1_value with the actual password. The password is an SHA1-hashed value rather than the original value. For example, if the password of the proxyro user is 123456, the observer_sys_password parameter must be set to 7c4a8d09ca3762af61e59520943dc26494f8941b.
2. Run the following command to specify the obproxy_config_server_url parameter in the startup command:
```
./bin/obproxy -p <obproxy_port> -n <appname> -o obproxy_config_server_url='your_config_url' -c <cluster_name>
```
  Parameters:
  - -p: specifies the port number listened to by the ODP. The MySQL client uses this port to access OceanBase Database. The parameter is required for the first startup. You do not need to specify this parameter in subsequent startups or upgrades.
  - -n: specifies the application name.
    
    You can use the app_name parameter to change the application name of the ODP. The default value is undefined.
  - -o: specifies the hardware or kernel parameter settings. If you do not specify this parameter, the default system configurations are used.
  - obproxy_config_server_url: specifies the URL of the config server.
  Example:
```
[admin@001 ~]$ ./bin/obproxy -p 2883 -n test -o "obproxy_config_server_url='http://xx.xx.xx.xx:8877/obproxy_config',observer_sys_password=$sha1_value,obproxy_sys_password=$sha1_value" -c mycluster
```
Run the following command to check whether the ODP process exists:
```
[admin@001 ~]$ ps -ef|grep obproxy
```

Note

The operation logs of ODP are stored in /opt/taobao/install/obproxy/log, namely /home/admin/logs/obproxy/log.

OceanBase Database connection example

When you connect to OceanBase Database through ODP, you must combine the cluster name, instance name, and username. There are four valid formats, with the first two being common.

Username@Tenant_name#Cluster_name
Cluster_name:Tenant_name:Username
Cluster_name-Tenant_name-Username
Cluster_name.Tenant_name.Username

$ obclient -h10.10.10.1 -uroot@sys#mycluster -P2883 -p -c -A
Enter password:
# Or
$ obclient -h10.10.10.1 -umycluster:sys:root -P2883 -p -c -A
Enter password:

Troubleshooting

Symptom: The following error is returned when the ODP is used to connect to OceanBase Database:

ERROR 2013 (HY000): Lost connection to MySQL server at 'reading authorization packet', system error: 0

Possible causes: The password specified by the observer_sys_password parameter in the ODP is inconsistent with the password of the proxyro user in OceanBase Database. The ODP cannot use this user account to communicate with the OBServer.

Solution: Adopt one of the following solutions based on the actual situation:

Connect to the OceanBase Database through a direct connection, and change the password of the proxyro user to the one that you set for the observer_sys_password parameter when you start the ODP.
```
ALTER USER proxyro IDENTIFIED BY 'password';
```
Log on to the ODP with the root@proxysys account and change the password of the proxyro@sys user. Then, restart the ODP.
```
alter proxyconfig set observer_sys_password = 'password';
```

Notice

In the password field in the preceding statement, enter the original value of the password instead of the SHA1-hashed value.