Configuring RedDog’s Server Behavior

Index

1. Introduction
2. Configuring configuration.properties
   1. language
   2. minimum_search_pattern_length
   3. max_number_result_authenticated_user
   4. max_number_result_unauthenticated_user
   5. owner_roles_*
   6. allow_multiple_search_wildcards
   7. allow_search_wildcard_anywhere
   8. allow_regex_searches
   9. user_roles
   10. notices_timer_update_time
   11. events_timer_update_time
   12. is_db_data_live
   13. add_custom_conformance
   14. add_email_remark
   15. is_country_code_released
   16. allow_labels_mixture

Introduction

RedDog’s behavior can be configured to satisfy whatever needs the implementer has. To achieve this, there’s a global configuration file located at folder WEB-INF/configuration.properties in the installation directory. Here’s a preview of the file’s beginning:

#Optional. Language of the server. Values en=english, es=español. Default: en
#language = 

#Optional. Minimum length of the search pattern. Default: 5
#minimum_search_pattern_length = 

#Optional. Max number of results for the authenticated user. Default: 20
#max_number_result_authenticated_user = 

#Optional. Max number of results for the unauthenticated user. Default: 10
#max_number_result_unauthenticated_user =

The next section will explain each of the properties that can be configured to customize RedDog’s server behavior.

Configuring configuration.properties

The configuration.properties file has several properties, each one with a specific task. In this section those properties and its expected behavior will be explained.

language

Language used at the server responses. This value will be set at the lang attribute of a RdapObject.

This table shows the specs of the property:

Required?	Type	Default	Example
	String	en	language = es

minimum_search_pattern_length

Minimum allowed length for search patterns. Any request where the search pattern length is smaller than this property value, will be rejected.

Examples. If the value is 5, this is the expected result for each case:

Request	Valid?
https://example.com/rdap/domains?name=dumm*
https://example.com/rdap/domains?name=dum*	search pattern length is 4
https://example.com/rdap/domains?name=dum**	search pattern length is 4 (consecutive wildcards are treated as one)

This table shows the specs of the property:

Required?	Type	Default	Example
	Integer	5	minimum_search_pattern_length = 6

max_number_result_authenticated_user

Maximum number of results that will be listed within responses to search requests made by authenticated users. This property indicates the default value for all authenticated users.

If the implementer wishes to customize the max number of results per user (eg. User A can see a max of 50 results, but user B can only see 30 results), the attribute maxSearchResults of the object RdapUser will be useful to achieve that.

This table shows the specs of the property:

Required?	Type	Default	Example
	Integer	20	max_number_result_authenticated_user = 30

max_number_result_unauthenticated_user

Maximum number of results that will be listed within responses to search requests made by unauthenticated users.

This table shows the specs of the property:

Required?	Type	Default	Example
	Integer	10	max_number_result_unauthenticated_user = 20

owner_roles_*

List of entity roles that should be able to see more information of a specific RDAP Object. Must be existing roles according to the catalog of RFC 7483 section 10.2.4.

To specify the owner of each RDAP Object, there’s a list of properties. These properties have the same validations but apply to distinct cases, just as their names prove it:

• owner_roles_ip
• owner_roles_autnum
• owner_roles_domain
• owner_roles_nameserver

The Entity object isn’t considered since it’s a generic object. Still, the next paragraph explains how an Entity object is treated.

A user (as confirmed by a successful Authorization header validation) will be considered the owner of a RDAP Object (Autnum, Domain, Entity, IP Network or Nameserver) if one of the following conditions is met:

• (If the RDAP Object is an Entity) The user’s username matches the object’s handle.
• (If the RDAP Object is not an Entity) The user’s username matches the handle of at least one of the object’s entities that has at least one role listed in owner_roles_*.

The following example will help to understand how this works. If the property owner_roles_domain value is registrant, and the server has this domain object with the corresponding entities related:

Domain (LDH name: "example.com")
  -> Entity (handle: "Alice", roles: "administrative")
  -> Entity (handle: "Bob",   roles: "registrant")
  -> Entity (handle: "Eve",   roles: "technical")

Then only the user “Bob” will be considered the owner of the domain “example.com”.

These properties work in conjunction with privacy settings.

This table shows the specs of each property:

Property	Required?	Type	Default	Example
owner_roles_ip		String (can be a list separated by commas)	administrative	owner_roles_ip = technical
owner_roles_autnum		String (can be a list separated by commas)	administrative	owner_roles_autnum = technical
owner_roles_domain		String (can be a list separated by commas)	registrant	owner_roles_domain = technical
owner_roles_nameserver		String (can be a list separated by commas)	registrar	owner_roles_nameserver = technical

allow_multiple_search_wildcards

Boolean flag to indicate if the wildcard ‘*’ can be used more than 1 time on each label of the search patterns. This property is used to comply with RFC 7482 section 4.1 allowing the use of the asterisk ‘*’ wildcard in searches.

The property is used to relieve the cost of searches that could be expensive to the server. If the property has a value of true then an object label can have more than one wildcard when used at partial searches, if false then only one wildcard per label will be allowed. The following table will help to comprehend this:

Property value	Search request	Valid?
false	https://example.com/rdap/domains?name=doma*
false	https://example.com/rdap/domains?name=dom*n.co*
false	https://example.com/rdap/domains?name=d*ma*.*o*
false	https://example.com/rdap/domains?name=d*ma*
true	https://example.com/rdap/domains?name=d*ma*
true	https://example.com/rdap/domains?name=doma*.co*
true	https://example.com/rdap/domains?name=d*ma*.*o*

This table shows the specs of the property:

Required?	Type	Default	Example
	Boolean	false	allow_multiple_search_wildcards = true

allow_search_wildcard_anywhere

Boolean flag to indicate if the wildcard ‘*’ can be used anywhere on each label of a search pattern. If the property has a value of true is valid to use the wildcard anywhere on each label of the search pattern, if false the wildcard can only be used at the end of each label.

If the property allow_multiple_search_wildcards is set to true, then the value of allow_search_wildcard_anywhere is indifferent.

The following table shows some examples on how this flag works:

Property value	Search request	Valid?
false	https://example.com/rdap/domains?name=doma*
false	https://example.com/rdap/domains?name=dom*n
false	https://example.com/rdap/domains?name=doma*.co*
false	https://example.com/rdap/domains?name=dom*n.c*m
true	https://example.com/rdap/domains?name=dom*n
true	https://example.com/rdap/domains?name=dom*n.co*

This table shows the specs of the property:

Required?	Type	Default	Example
	Boolean	false	allow_search_wildcard_anywhere = true

allow_regex_searches

Boolean flag to indicate if the server will support extended searches using REGEX. If the property has a value of true the server will support the behavior stated at draft Registration Data Access Protocol (RDAP) Search Using POSIX Regular Expressions v01 (see examples at the table below), if false then this behavior will be disabled (the parameter searchtype will be ignored).

The feature is based on a draft, so it isn’t quite updated, use it cautiously. Hopefully this will be updated on a later release.

The following table shows some examples on how this flag works:

This table shows the specs of the property:

Required?	Type	Default	Example
	Boolean	false	allow_regex_searches = true

user_roles

List of strings representing custom user roles that can be used to configure privacy settings. The roles defined here MUST NOT have any of these values: any, none, owner, or authenticated; since those are reserved words used at privacy settings.

Since each role is expected to be a String, any value (except for the reserved words) that suites the implementer needs can be used, still it’s recommended to use alphanumeric values. When using roles, its value is used and validated as case insensitive.

This table shows the specs of the property:

Required?	Type	Default	Example
	String (can be a list separated by commas)	null	user_roles = president, governor, judge

notices_timer_update_time

Integer number that represents time in seconds. It is used by a notices update timer that checks every N seconds, if exists a change in the notices files for each type of requests (i.e. entity, domain, nameserver, autnum, ip)

if the value is less than 10 (0 - default value), the timer for the notices will never start nor check for updates. To update the notices, you will need to restart the application. This functionality behave this way because not every implementer needs to update notices too often.

Required?	Type	Default	Example
	Integer	0	notices_timer_update = 3600

events_timer_update_time

Integer number that represents time in seconds. It is used by an event update timer that checks every N seconds, if exists a change in the event file.

if the value is less than 10 (0 - default value), the timer for the events will never start nor check for updates. To update the events, you will need to restart the application. This functionality behave this way because not every implementer needs to update events too often.

Required?	Type	Default	Example
	Integer	0	events_timer_update = 3600

is_db_data_live

Boolean value to override the timestamp in the eventAction type last update of RDAP database on first level RDAP objects.

It is used when the RDAP service provider is querying its database directly, and therefore, using real-time data, so for every request, the timestamp value will be overridden to the server timestamp when the request was made.

In case that the event last update of RDAP database event does not exist, this flag will create an event in the first level RDAP object.

Required?	Type	Default	Example
	Boolean	false	is_db_data_live = false

add_custom_conformance

Rdap Conformances (separated by commas) to be displayed in the result response.

It is used when the RDAP service wants to add custom conformance to the response, e.g. If your RDAP service is compliant with ICANN’s RDAP profile, you can add the conformance that tells that you are complying with the profile.

Required?	Type	Default	Example
	Strings sepparated by commas	empty	add_custom_conformance = lunar_nic_0

add_email_remark

Boolean value.

Indicates if Email remark (from section 2.7.5.3 in ICANN’s RDAP response profile) needs to be added to the domain response.

Required?	Type	Default	Example
	Boolean	false	add_email_remark = true

is_country_code_released

Boolean value

Indicates If the ISO-3166-1-alpha-2 parameter has been published in the vCard Properties and handle according to the ICANN’s RDAP response profile section 1.4

Required?	Type	Default	Example
	Boolean	false	is_country_code_released = true

allow_labels_mixture

Boolean value

Indicates if the RDAP server that receives a query string (for domain name or nameserver objects) with a mixture of A-labels and U-labels should reject the query and return an HTTP 400 Bad Request response.

Required?	Type	Default	Example
	Boolean	true	allow_labels_mixture = false

Where to go next