Skip to content

Latest commit

 

History

History
173 lines (110 loc) · 5.5 KB

README.md

File metadata and controls

173 lines (110 loc) · 5.5 KB
Raw

Dothan

GitHub Release GitHub Docs Site

A light TCP proxy. You can take it as MySQL proxy, might also work for SSH.

And the man said, They are departed hence; for I heard them say, Let us go to Dothan. And Joseph went after his brethren, and found them in Dothan. (Genesis 37:17 )

And he said, Go and spy where he [is], that I may send and fetch him. And it was told him, saying, Behold, [he is] in Dothan....And Elisha said unto them, This [is] not the way, neither [is] this the city: follow me, and I will bring you to the man whom ye seek. But he led them to Samaria. (2 Kings 6:13,19)

Package

Since Version 6, new package io.github.sinri.Dothan is adopted to the this project.

Maven Access

OSS-SONATYPE

<dependency>
  <groupId>io.github.sinri</groupId>
  <artifactId>Dothan</artifactId>
  <version>6.0.1</version>
</dependency>

Deploy Note

You should export your JAVA_HOME first. In Mac OS X, you may run /usr/libexec/java_home to get correct path for it.

Commonly snapshot is used for quick deploy with default version tag 6.0-SNAPSHOT or so, run mvn clean package deploy -P snapshot to update.

To release new version to OSS-SONATYPE, run mvn clean package deploy -P release after correcting the version.

Environment

  • Java 8

Maven Dependencies

  • io.vertx core
  • Apache commons cli
  • Apache commons validator

License

GPLv3

Get Runnable Package

You can obtain the runnable package in two ways.

  1. Download JAR file from GitHub release area.
  2. Use Maven 3, run mvn clean package.

Usage (As of Version 2.0)

usage: options

 -b <arg>   blacklist, separate IP with comma (as of 4.0)
 -c <arg>   Set proxy config file. If not use this, h,p and l are needed.
 -d         use detail mode
 -h <arg>   database host
 -help      Display help information
 -k         keep config and no hot update
 -l <arg>   listen local port
 -p <arg>   database port
 -w <arg>   whitelist, separate IP with comma (as of 4.0)

Quick Proxy

Run Dothan quickly for one proxy, host, port and listen port are required, and detail mode is also available.

java -jar Dothan.jar -d -hdatabase.com -p3306 -l20001

Configured Proxy

You should provide a config file as config parameter.

The config file should contain one or more lines and each for one proxy requirement. The format is [LISTEN_PORT]:[SERVER_HOST]:[SERVER_PORT] as of 5.0. Previous format [LISTEN_PORT] [SERVER_HOST]:[SERVER_PORT] is still supported though not recommended now.

The lines with leading Sharp(#) would be treated as comments.

The lines with leading Plus(+) would be treated as IP Address in whitelist. If no such lines, whitelist is ignored.

The lines with leading Minus(-) would be treated as IP Address in blacklist. If no such lines, blacklist is ignored.

Here is an example:

# Dothan Config [SAMPLE]

+ 127.0.0.1
- 192.168.0.2

20001:1.rds.aliyuncs.com:3306
20002:2.rds.aliyuncs.com:3306

The command would be as following if the config file path is /path/to/Dothan.config.

java -jar Dothan.jar -d -c /path/to/Dothan.config

Hot Update Version

As of version 3.0, the hot version update is available for Config-File Mode.

This relies on the version declaration in configuration file as a line:

# Dothan Config Version VERSION_CODE

The version code should be an positive integer. If there are more than one line in this format, the last would be used. The file would be watched by the Dothan process and update config if the current version code became greater.

Since version 3.1, Dothan uses WatchService for hot update function, and provide a parameter (-k) to disable hot update.

Translate Mode

We have to admit, the network is not so safe. That is why the service provider make databases not accessible from outside. However, we have certain time to access to such service, but we may be afraid that our connections would be seen by others through public network. So we might use the translate mode to pass our data encrypted, with two new parameters MODE and TRANSFER KEY, as of version 5.0.

                  [CLIENT] 
                    |  ↑
       PLAIN TEXT   |  |   PLAIN TEXT
                    ↓  |
      encrypt [DOTHAN   LOCAL] decrypt
                    |  ↑
       SECRET BYTES |  | SECRET BYTES
                    ↓  |
      decrypt [DOTHAN  REMOTE] encrypt
                    |  ↑
       PLAIN TEXT   |  |   PLAIN TEXT
                    ↓  |
             [SERVICE PROVIDER]

On DOTHAN LOCAL the config file should contain transfer mode ENCRYPT and key.

# MODE ENCRYPT
# TRANSFER KEY t8o7diugf8iauyvge8iu

[DOTHAN_LOCAL_PORT]:[DOTHAN_REMOTE_ADDRESS]:[DOTHAN_REMOTE_PORT]

While on DOTHAN REMOTE the config file should contain transfer mode DECRYPT and key.

# MODE DECRYPT
# TRANSFER KEY t8o7diugf8iauyvge8iu

[DOTHAN_REMOTE_PORT]:[SERVER_ADDRESS]:[SERVER_PORT]

So your request sent to the DOTHAN_LOCAL_PORT of DOTHAN LOCAL would be transferred to DOTHAN REMOTE and finally reach the actual service provider.

If you like, you can use more than one Dothan pair to make the connection chain.

Museum: Version 1.1 (deprecated)

java -jar target/Dothan-1.1-SNAPSHOT.jar some.mysql.rds.aliyuncs.com 3306 33306