Domain name resolution can be customized by setting a Host mapper in the service or forwarding chain.
Host mapper supports dynamic configuration via Web API.
A host mapper is a hostname-to-IP address mapping table. When domain name resolution needs to be performed, first check whether there is a corresponding mapping in the mapper, and if so, use the IP address directly. If it is not defined in the mapper, then use the DNS service to query.
Mapper In Service¶
The handler in service will use the mapper to try to resolve the request target address before establishing a connection with the target host.
The mapping table is specified by the
hosts option. The mapping item is a host:IP pair separated by
:, and the IP can be in IPv4 or IPv6 format.
Services use the
hosts property to use the specified mapper by referencing the mapper name.
Mapper In Chain¶
A mapper can be set on hop or node in the forwarding chain. When no mapper is set on the node, the mapper on the hop is used.
The mapping table is specified by the
hosts option. The
hosts option corresponds to the mapper at the hop level in the configuration file.
services: - name: service-0 addr: ":8000" handler: type: http chain: chain-0 listener: type: tcp chains: - name: chain-0 hops: - name: hop-0 # hop level hosts hosts: hosts-0 nodes: - name: node-0 addr: example.com:8080 # node level hosts # hosts: hosts-0 connector: type: http dialer: type: tcp hosts: - name: hosts-0 mappings: - ip: 127.0.0.1 hostname: example.com - ip: 2001:db8::1 hostname: example.com
hosts property in the hop or node of the forwarding chain to use the specified mapper by referencing the mapper name.
The mapper is directly applied to DNS query requests in the DNS proxy service to implement custom domain name resolution.
Then query example.org through this DNS proxy service will match the definition in the mapper and not query with 184.108.40.206.
Domain names in mappers also support a special wildcard format starting with
.example.org matches domain example.org, and subdomains like abc.example.org, def.abc.example.org, etc.
When querying, it will first look for the exact match, if not found, then look for the wildcard item, if not found again, then look for the upper-level domain name wildcard in turn.
For example: abc.example.org, the mapping value of abc.example.org will be searched first (exact match), if not found, the .abc.example.org wildcard item will be searched, and if not, the .example.org and .org wildcard items will be searched in turn.
Mapper can configure multiple data sources, currently supported data sources are: inline, file, redis.
An inline data source means setting the data directly in the configuration file via the
Specify an external file as the data source. Specify the file path via the
The file format is mapping items separated by lines, each line is an IP-host pair separated by spaces, and the part starting with
# is the comment information.
System hosts File
The file data source is compatible with the system hosts file format, and the hosts file of the system can be used directly.
- redis server address
- database name
- redis key
- data type:
Similar to the format of file data sources, each item is a space-separated IP-host pair:
Specify the HTTP service as the data source. For the requested URL, if HTTP returns a 200 status code, it is considered valid, and the returned data format is the same as the file data source.
- request URL
- request timeout
When configuring multiple data sources at the same time, the priority from high to low is: HTTP, redis, file, inline.
File, redis and HTTP data sources support hot reloading. Enable hot loading by setting the
reload property, which specifies the period for synchronizing the data source data.
Host Mapper can be configured to use an external plugin service, and it will forward the request to the plugin server for processing. Other parameters are invalid when using plugin.
- plugin server address.
- TLS encryption will be used for transmission, TLS encryption is not used by default.
- network type:
- host address
- user ID, generated by Authenticator plugin.
- IP address list