ICANN RDAP Users Manual

This is the user's manual for the ICANN-RDAP project, an open-source implementation of the Registry Data Access Protocol (RDAP). ICANN-RDAP includes four sub-projects.

Command Line Tools

There are two command line tools, rdap and rdap-test.

The rdap command is an easy-to-use, full-featured command line client.

The rdap-test is an easy-to-use troubleshooting tool meant to help users identify issues.

Rust Libraries

The Rust libraries are available from crates.io:

Common Library contains Rust structs and functions for RDAP. This library has been incorporated into custom, production RDAP servers and other software.
Client Library has useful functions for querying RDAP servers, including bootstrapping. This library has been incorporated into custom, product clients such as intrusion detection systesm.

An RDAP Server

This is an easy-to-use RDAP server that has in-memory storage and requires no infrastucture. This server is ideal for prototyping and testing.

Command Line Client

The `rdap` Command

The rdap command is an easy-to-use, full-featured, command-line interface (CLI) client for RDAP. It supports RDAP bootstrapping, caching, different output formats, link following, and the following extensions:

Cidr0
Exts
JSContact
Redacted
SimpleRedaction

Installation

From a Package Manager

Homebrew

For Linux, macOS, and Windows Subsystem for Linux:

brew install icann-rdap

Arch Linux AUR

Several packages are available in the AUR:

https://aur.archlinux.org/packages?O=0&SeB=nd&K=icann-rdap&outdated=&SB=p&SO=d&PP=50&submit=Go

Pre-Built Binaries

Pre-built binaries are available for most mainstream systems: x86_64 and Arm 64bit for Linux GNU systems, x86_64 and Arm 64bit macOS, and x86_64 for Windows. You may find the pre-built binaries on the Releases page.

For non-Debian-based Linux, compiling from crates.io or source (both are easy) is recommended to avoid issues with dynamic linking to OpenSSL.

Compiling from crates.io

If you have Rust installed on your system, then compiling from source is very straightforward. If you do not have Rust installed on your system, it is usually very easy to do: see Rustup.

If you are on a Linux system, you will need OpenSSL development files. For Debian and Ubuntu, this is usually done via apt install pkg-config libssl-dev. For other Linux systems, consult your packaging documentation.

For macOS and Windows, the native TLS libraries are used, and there are no steps needed to install them.

To build and install: cargo install icann-rdap-cli.

Compiling from Source

If you have Rust installed on your system, then compiling from source is very straightforward. If you do not have Rust installed on your system, it is usually very easy to do: see Rustup.

If you are on a Linux system, you will need OpenSSL development files. For Debian and Ubuntu, this is usually done via apt install pkg-config libssl-dev. For other Linux systems, consult your packaging documentation.

For macOS and Windows, the native TLS libraries are used, and there are no steps needed to install them.

Run the tests: cargo test

Then build the software: cargo build --release. The executable binaries will be available in the target/release directory.

Quick Start

Basic Queries

Domain: rdap example.com
TLD: rdap .com
IP Address: rdap 192.0.2.1
CIDR: rdap 10/8
ASN: rdap as64496
URL: rdap https://rdap.iana.org/domain/com

Command Help

brief: rdap -h
extended: rdap --help

Domain Queries

This page provides detailed information about querying domain names using the RDAP command line client.

Basic Domain Queries

Simple Domain Lookup

The most common use case is querying information about a specific domain name:

rdap example.com

This command will: - Automatically detect that "example.com" is a domain name - Use the RDAP bootstrap process to find the authoritative server - Display the domain information

Explicit Domain Type Specification

You can explicitly specify the query type to avoid automatic inference:

rdap -t domain example.com

This is useful when the query value might be ambiguous or when you want to ensure domain-specific processing.

A-Label Domain Queries

For internationalized domain names (IDNs) in their ASCII (A-label) form:

rdap -t alabel xn--d1acj3b

Server Targeting Options

Link Target Parameters for Registry and Registrar

The --registry and --registrar flags are used for controlling link following behavior when querying domains:

Registry Link Following

# Follow links to domain registry information
rdap --registry icann.org

This sets link target parameters to query the registry associated with the domain, with: - Only showing the target information - Minimum link depth: 1 - Maximum link depth: 1

Registrar Link Following

# Follow links to domain registrar information
rdap --registrar icann.org

This sets link target parameters to query the registrar associated with the domain, with: - Link targets: "related" - Only showing the target information - Minimum link depth: 2 - Maximum link depth: 3

Combined with Depth Control

# Follow registrar links with custom depth
rdap --registrar --max-link-depth 5 example.com

# Follow registry links with depth control
rdap --registry --min-link-depth 1 --max-link-depth 2 example.com

Bootstrap Registry Selection

Direct queries to a specific registry using its bootstrap identifier with -b or --base flag:

# Query the .com registry
rdap -b com example.com

# Query the ARIN registry
rdap -b arin 1.2.0.192.in-addr.arpa

# Query the RIPE NCC registry
rdap -b ripe 1.2.0.192.in-addr.arpa

Explicit Server URL

Direct queries to a specific RDAP server with -B or --base-url flag:

rdap -B https://rdap.iana.org com
rdap -B https://rdap.example.net example.com

This bypasses the bootstrap process and sends the query directly to the specified server.

TLD Queries

Query information about a top-level domain itself:

rdap .com
rdap .org
rdap .net

This will query IANA's RDAP server for information about the TLD.

IP Address Queries

This page provides detailed information about querying IP addresses and networks using the RDAP command line client.

Basic IP Address Queries

IPv4 Address Lookup

Query information about a specific IPv4 address:

rdap 192.0.2.1

This command will: - Automatically detect that "192.0.2.1" is an IPv4 address - Use the RDAP bootstrap process to find the appropriate Regional Internet Registry (RIR) - Display network and entity information

IPv6 Address Lookup

Query information about a specific IPv6 address:

rdap 2001:db8::1

Explicit IP Type Specification

You can explicitly specify the query type to avoid automatic inference:

# IPv4 address
rdap -t v4 192.0.2.1

# IPv6 address  
rdap -t v6 2001:db8::1

CIDR Block Queries

IPv4 CIDR Queries

Query information about IPv4 networks using CIDR notation:

rdap -t v4cidr 192.0.2.0/24

This will return information about the entire /24 network block.

IPv6 CIDR Queries

Query information about IPv6 networks using CIDR notation:

rdap -t v6cidr 2001:db8::/32

Short CIDR Notation

For common network sizes, you can use abbreviated notation:

# Equivalent to 192.0.2.0/24
rdap 192.0.2/24

# Equivalent to 2001:db8::/32
rdap 2001:db8/32

Reverse DNS Queries

IP Address Reverse DNS

Query reverse DNS information for an IP address:

rdap -t rdns 192.0.2.1

This performs a reverse DNS lookup and returns the corresponding RDAP information.

Reverse DNS for CIDR Blocks

You can also perform reverse DNS queries on network blocks:

rdap -t rdns 192.0.2.0/24

Server Targeting Options

Bootstrap Registry Selection

Direct queries to a specific RIR using its bootstrap identifier:

# Query ARIN specifically
rdap -b arin 192.0.2.1

# Query RIPE NCC
rdap -b ripe 192.0.43.8

# Query APNIC
rdap -b apnic 203.0.113.1

Common RIR identifiers: - arin - American Registry for Internet Numbers - ripe - RIPE Network Coordination Centre
- apnic - Asia-Pacific Network Information Centre - lacnic - Latin America and Caribbean Network Information Centre - afrinic - African Network Information Centre

Explicit Server URL

Direct queries to a specific RDAP server:

rdap -B https://rdap.arin.net/registry/ip/192.0.2.1

This bypasses the bootstrap process and sends the query directly to the specified server.

INR Backup Bootstrap

When normal bootstrapping fails for IP addresses, you can specify a backup:

# Use ARIN as backup (default)
rdap --inr-backup-bootstrap arin 192.0.2.1

Link Following

Follow related objects (like parent networks) automatically:

Network Hierarchy Link Following

# Follow to parent networks (less specific)
rdap --up 192.0.2.1

# Follow to child networks (more specific)
rdap --down 192.0.2.1

# Follow to least specific network
rdap --top 192.0.2.1

# Follow to most specific network
rdap --bottom 192.0.2.1

Autonomous System Number (AS Number) Queries

This page provides detailed information about querying Autonomous System Numbers (ASNs) using the RDAP command line client.

Basic AS Number Queries

Simple AS Number Lookup

Query information about a specific Autonomous System Number:

rdap as64496

This command will: - Automatically detect that "as64496" is an AS number - Use the RDAP bootstrap process to find the appropriate Regional Internet Registry (RIR) - Display AS information

Explicit AS Number Type Specification

You can explicitly specify the query type to avoid automatic inference:

rdap -t autnum as64496

AS Number Formats

Standard AS Number Format

The most common format uses the "as" prefix followed by the number:

rdap as64496

Numeric-Only Format

You can also query using just the numeric portion:

rdap 64496

Server Targeting Options

Bootstrap Registry Selection

Direct queries to a specific RIR using its bootstrap identifier:

# Query ARIN specifically
rdap -b arin as64496

# Query RIPE NCC
rdap -b ripe as65536

# Query APNIC
rdap -b apnic as13335

Common RIR identifiers for AS numbers: - arin - American Registry for Internet Numbers - ripe - RIPE Network Coordination Centre
- apnic - Asia-Pacific Network Information Centre - lacnic - Latin America and Caribbean Network Information Centre - afrinic - African Network Information Centre

Explicit Server URL

Direct queries to a specific RDAP server:

rdap -B https://rdap.arin.net/registry/autnum/64496

This bypasses the bootstrap process and sends the query directly to the specified server.

INR Backup Bootstrap

When normal bootstrapping fails for AS numbers, you can specify a backup:

# Use ARIN as backup (default)
rdap --inr-backup-bootstrap arin as64496

Redaction Handling

This client supports the "redacted" extension documented in RFC 9537. However, RFC 9537 redactions are extremely complicated and often confusing to users. This client, when possible, will convert RFC 9537 redactions to "simpleRedactions".

Redaction Flags

The client supports several redaction flags that can be combined to control redaction behavior:

Highlight Simple Redactions

rdap --redaction-flag highlight-simple-redactions example.com

This flag highlights simple redactions in the output, making them more visible when displayed in terminals.

Show RFC 9537 Redaction Directives

rdap --redaction-flag show-rfc9537 example.com

This flag displays detailed RFC 9537 redaction directive information, including reasons and authorities.

Do Not Simplify RFC 9537 Redactions

rdap --redaction-flag do-not-simplify-rfc9537 example.com

This flag prevents RFC 9537 redactions from being converted to simple redactions, preserving the detailed directive information.

Process RFC 9537 Redactions

rdap --redaction-flag do-rfc9537-redactions example.com

This flag enables full processing of RFC 9537 redactions, applying all specified redaction rules and directives.

Redaction Flag Combinations

You can combine multiple redaction flags using commas:

# Highlight simple redactions and show RFC 9537 directives
rdap --redaction-flag highlight-simple-redactions,show-rfc9537 example.com

# Process RFC 9537 redactions without simplifying them
rdap --redaction-flag do-rfc9537-redactions,do-not-simplify-rfc9537 example.com

Environment Variable Configuration

Set default redaction flags using the RDAP_REDACTION_FLAGS environment variable:

export RDAP_REDACTION_FLAGS=highlight-simple-redactions,show-rfc9537

Output Format Control

This page provides detailed information about controlling the output format of RDAP responses using the RDAP command line client.

Overview

The RDAP client supports multiple output formats to accommodate different use cases, from human-readable terminal output to machine-readable formats for automation. You can control the output format using command-line options or environment variables.

Output Format Options

Auto Detection (Default)

By default, the client automatically determines the best output format:

# normal user output
rdap example.com

# json output for non-interactive (e.g., scripting)
rdap example.com | jq .

Interactive terminals: Rendered markdown with ANSI colors
Non-interactive: Compact JSON
Configuration: Can be overridden with -O command line flag.

Markdown Formats

Rendered Markdown

rdap -O rendered-markdown example.com
# or default for interactive terminals
rdap example.com

Output is rendered with ANSI terminal capabilities including: - Color coding - Highlighting - Terminal-specific formatting

Plain Text Markdown

rdap -O markdown example.com

Output is in plain markdown format suitable for: - Documentation systems - Plain text files - Non-ANSI terminals

JSON Formats

Compact JSON

rdap -O json example.com

Standard JSON output with minimal whitespace, ideal for: - Script processing - API responses - Data storage

Pretty JSON

rdap -O pretty-json example.com

Human-readable JSON with indentation and line breaks, ideal for: - Debugging - Development - Manual inspection

Pretty Compact JSON (Recommended)

rdap -O pretty-compact-json example.com
# or shortcut:
rdap --json example.com

JSON output that is both compact and readable, providing: - Intelligent line breaks - Strategic indentation - Optimal balance for human and machine reading

JSON with Extra Information

rdap -O json-extra example.com

Includes additional metadata such as: - HTTP request/response data - Processing timestamps - Internal state information - Request/response correlation data

Specialized Formats

gTLD WHOIS Format

rdap -O gtld-whois example.com

Traditional WHOIS-style format for gTLD domains, featuring: - WHOIS-compatible output - Line-based formatting - Legacy system compatibility

Note: Only available for domain queries.

Routing Policy Specification Language (RPSL)

rdap -O rpsl 192.0.2.1
# or shortcut:
rdap --rpsl 192.0.2.1

RPSL format for network routing information, ideal for: - Network management systems - Routing policy databases - ISP automation

Status and Event Formats

Status Text

rdap -O status-text example.com

Outputs only the primary object's status, one status per line.

Status JSON

rdap -O status-json example.com

Outputs only the primary object's status in JSON format.

Event Text

rdap -O event-text example.com

Outputs only the primary object's events (creation, expiration, etc.), one per line.

Event JSON

rdap -O event-json example.com

Outputs only the primary object's events in JSON format.

URL Output

rdap -O url example.com

Outputs only the RDAP server URL for the query, useful for: - Debugging - URL extraction - Server verification

Environment Variable Configuration

Set default output format using RDAP_OUTPUT environment variable:

# Set default to pretty compact JSON
export RDAP_OUTPUT=pretty-compact-json

# Set default to rendered markdown
export RDAP_OUTPUT=rendered-markdown

# Set default to RPSL
export RDAP_OUTPUT=rpsl

Usage

Exit Codes

Here's a summary of the rdap command exit codes, based on error.rs:

Exit Code	Description	Category
0	Success	Success
10	`termimad` error	Internal Error
11	`minus` error	Internal Error
40	I/O error	I/O Error
42	Client error (within `RdapClient`)	I/O Error (rdap client)
43	I/O error (within `RdapClient`)	I/O Error (rdap client)
60	Response error (within `RdapClient`)	RDAP Server Error
62	Parsing error (within `RdapClient`)	RDAP Server Error
63	JSON error (within `RdapClient`)	RDAP Server Error
70	Bootstrap unavailable (within `RdapClient`)	Bootstrap Error
71	Bootstrap error (within `RdapClient`)	Bootstrap Error
72	IANA response error (within `RdapClient`)	Bootstrap Error
100	JSON error	RDAP Error
101	IANA error	RDAP Error
102	Invalid bootstrap file	RDAP Error
103	Bootstrap not found	RDAP Error
104	No registrar found	RDAP Error
105	No registry found	RDAP Error
200	Unknown output type	User Error
201	Error on checks	User Error
202	Invalid query value (within `RdapClient`)	User Error
203	Ambiguous query type (within `RdapClient`)	User Error
204	Domain name error (within `RdapClient`)	User Error
250	Poison error (internal to rdap client)	Internal Error

Paging Output

The client has a built-in (embedded) pager. Use of this pager is controlled via the RDAP_PAGING environment variable and the -P command argument.

It takes three values:

"embedded" - use the built-in pager
"auto" - use the built-in pager if the program is being run from a terminal
"none" - use no paging

For example, -P embedded will default to using the built-in pager.

By default, the client will not use a pager.

When set to "auto", the client determines if a pager is appropriate. This is done by attempting to determine if the terminal is interactive or not. If the terminal is not interactive, paging will be turned off otherwise it will be on.

Output Format

By default, the client will attempt to determine the output format of the information. If it determines the shell is interactive, output will be in rendered-markdown. Otherwise, the output will be JSON.

You can explicitly control this behavior using the -O command argument or the RDAP_OUTPUT environment variable (see below).

Directing Queries To A Specific Server

By default, the client will use the RDAP bootstrap files provided by IANA to determine the authoritative server for the information being requested. These IANA files have the "base URLs" for the RDAP servers. This is a process known as "bootstrapping".

You can override this behavior by either specifying a base "object tag" from the IANA object tags registry or with an explicit URL (e.g. rdap https://foo.example/ip/10.0.0.0).

An object tag can be specified with the -b command argument or the RDAP_BASE environment variable (see below). For example, -b arin will direct the client to find the ARIN server in the RDAP object tag registry.

An explicit base URL can be specified using the -B command or the RDAP_BASE_URL environment variable.

Two additional arguments are provided to assist with bootstrapping: * --tld-lookup - Specifies where to send queries for TLDs such as ".com". This defaults to IANA. * --inr-backup-bootstrap - Specifies where to send queries for IP addresses and ASNs should normal bootstrapping not yield an answer. This defaults to ARIN.

Caching

By default, the client will cache data based on the request URL and "self" links provided in the RDAP results.

This can be turned off with the -N command parameter or by setting the RDAP_NO_CACHE environment variable to "true".

The --max-cache-age argument controls the maximum amount of time items are left in the cache.

Logging

The client logs errors, warning, and other information on its processing. This can be controlled with the --log-level command argument or the RDAP_LOG environment variable.

Secure Connections

By default, the client will use secure connections. The following arguments and environment variables can be used to modify this behavior:

-T or RDAP_ALLOW_HTTP : RDAP servers should be using HTTPS. When given or set to true, HTTP will be allowed.
-K or RDAP_ALLOW_INVALID_HOST_NAMES : Allows HTTPS connections in which the host name does not match the certificate.
-I or RDAP_ALLOW_INVALID_CERTIFICATES : Allows HTTPS connections in which the TLS certificate is invalid.

Retries and Timeouts

By default, the client will retry queries if given an HTTP 429 response. The following arguments and environmental variables can be used to modify this behavior:

--max-retries or RDAP_MAX_RETRIES: Number of retries to attempt. Default is 1.
--max-retry-secs or RDAP_MAX_RETRY_SECS: Maximum number of seconds to wait before a retry if the retry-after value is greater.
--def-retry-secs or RDAP_DEF_RETRY_SECS: Default number of seconds to wait before a retry if no retry-after value is provided by the server.

The --timeout-secs argument determines the total time the client will wait for an answer.

Conformance Checks

Some specification conformance checks are done by this client. Each conformance check is assigned a number. These numerical values may be found here. Additionally, each check is classified into one of the following classes:

Informational
Specification Note
Standards Warning
Standards Error
Cidr0 Extension Error
ICANN Extension Error

The --error-on-checks argument will cause the client to exit with a non-zero exit code (see above) if one of these errors is detected. This may be useful for certain scripting purposes.

The --check-type argument may be used to specify which types of checks will be evaluating when the --error-on-checks argument causes a non-zero exit code.

Configuration

Configuration of this program may be set using environment variables or using an environment variables configuration file in the configuration directory of this program. An example is automatically written to the configuration directory. This configuraiton file may be customized by uncommenting out the provided environment variable settings.

The location of the configuration file is platform dependent.

On Linux, this file is located at $XDG_CONFIG_HOME/rdap/rdap.env or $HOME/.config/rdap/rdap.env.

On macOS, this file is located at $HOME/Library/Application Support/rdap/rdap.env.

On Windows, this file is located at {FOLDERID_RoamingAppData}\rdap\config\rdap.env.

Resetting

Use the --reset argument to reset all client state. This will remove the RDAP and IANA caches and reset the rdap.env file (see above) to the default.

Test Tool

The `rdap-test` Command

The rdap-test command is a command-line interface (CLI) testing utility. The purpose of this command is to help RDAP service operators improve their services. This command does not cover all issues with RDAP and is intended as yet another tool to help improve RDAP. This command is not a substitute for more comprehensive tools such the ICANN RDAP Conformance Tool.

The rdap-test command can directly output JSON and has a set of exit codes making it easy to integrate into CI/CD pipelines and other software development practices. This command can also use RDAP bootstrapping, including referral chasing, enabling the tests for finding of authoritative RDAP services.

Installation

From a Package Manager

Homebrew

For Linux, macOS, and Windows Subsystem for Linux:

brew install icann-rdap

Arch Linux AUR

Several packages are available in the AUR:

https://aur.archlinux.org/packages?O=0&SeB=nd&K=icann-rdap&outdated=&SB=p&SO=d&PP=50&submit=Go

Pre-Built Binaries

Pre-built binaries are available for most mainstream systems: x86_64 and Arm 64bit for Linux GNU systems, x86_64 and Arm 64bit macOS, and x86_64 for Windows. You may find the pre-built binaries on the Releases page.

For non-Debian-based Linux, compiling from crates.io or source (both are easy) is recommended to avoid issues with dynamic linking to OpenSSL.

Compiling from crates.io

If you have Rust installed on your system, then compiling from source is very straightforward. If you do not have Rust installed on your system, it is usually very easy to do: see Rustup.

If you are on a Linux system, you will need OpenSSL development files. For Debian and Ubuntu, this is usually done via apt install pkg-config libssl-dev. For other Linux systems, consult your packaging documentation.

For macOS and Windows, the native TLS libraries are used, and there are no steps needed to install them.

To build and install: cargo install icann-rdap-cli.

Compiling from Source

If you have Rust installed on your system, then compiling from source is very straightforward. If you do not have Rust installed on your system, it is usually very easy to do: see Rustup.

If you are on a Linux system, you will need OpenSSL development files. For Debian and Ubuntu, this is usually done via apt install pkg-config libssl-dev. For other Linux systems, consult your packaging documentation.

For macOS and Windows, the native TLS libraries are used, and there are no steps needed to install them.

Run the tests: cargo test

Then build the software: cargo build --release. The executable binaries will be available in the target/release directory.

Quick Start

Basic Queries

Domain: rdap-test --registry icann.org
Domain @ registrar: rdap-test --registrar icann.org
Expect gTLD conformance: rdap-test -g gtld icann.org
URL: rdap-test https://rdap.iana.org/domain/com
JSON format: rdap-test -O json icann.org

Command Help

brief: rdap-test -h
extended: rdap-test --help

Usage

Exit Codes

Exit Code	Description	Category
0	Success	Success
1	Tests completed with execution errors.	Test Failure
2	Tests completed, warning checks found.	Test Warning
3	Tests completed, error checks found.	Test Failure
10	Internal error related to terminal display (termimad)	Internal Error
40	I/O Error or Test Execution Error	I/O Error
42	RDAP Client Error - Client	RDAP Client Error
43	RDAP Client Error - I/O	RDAP Client Error
60	RDAP Client Error - Response	RDAP Client Error
62	RDAP Client Error - Parsing Error	RDAP Client Error
63	RDAP Client Error - JSON	RDAP Client Error
70	RDAP Client Error - Bootstrap Unavailable	RDAP Client Error
71	RDAP Client Error - Bootstrap Error	RDAP Client Error
72	RDAP Client Error - IANA Response	RDAP Client Error
100	JSON error	RDAP Error
101	IANA error	RDAP Error
102	Invalid IANA bootstrap file	RDAP Error
103	Bootstrap not found	RDAP Error
104	No registrar found	RDAP Error
105	No registry found	RDAP Error
200	Unknown output type	User Error
202	RDAP Client Error - Invalid Query Value	RDAP Client Error
203	RDAP Client Error - Ambiguous Query Type	RDAP Client Error
204	RDAP Client Error - Domain Name Error	RDAP Client Error
250	RDAP Client Error - Internal Poison Error	RDAP Client Error

Test Controls

The following arguments may be used to control the behavior of tests:

--skip-v4 - Skip v4 tests.
--skip-v6 - Skip v6 tests.
--skip-origin - Skip tests using the HTTP "origin" header.
--origin-value - Set the "origin" header value.
--one-addr - Only test one address.

Link Target Controls

The following arguments may be used to control link following behavior during tests:

--link-target - Specifies a link target. More than one link target may be given.
--only-show-target - When specified, only link target results are shown.
--min-link-depth - Sets the minimum number of times to query for a link target.
--max-link-depth - Sets the maximum number of times to query for a link target.

Network Hierarchy Link Targets

--up - Set link target parameters for a parent network.
--down - Set link target parameters for child networks.
--top - Set link target parameters for least specific network.
--bottom - Set link target parameters for most specific network.

Domain-Specific Link Targets

--registry - Set link target parameters for a domain registry.
--registrar - Set link target parameters for a domain registrar.

Link Target Examples

# Test with registry link following
rdap-test --registry https://rdap.nic.com/domain/example.com

# Test with registrar link following
rdap-test --registrar https://rdap.nic.com/domain/example.com

# Test with network hierarchy following
rdap-test --up https://rdap.arin.net/registry/ip/192.0.2.1
rdap-test --down https://rdap.arin.net/registry/ip/192.0.2.1
rdap-test --top https://rdap.arin.net/registry/ip/192.0.2.1
rdap-test --bottom https://rdap.arin.net/registry/ip/192.0.2.1

# Test with custom link depth
rdap-test --link-target entity --max-link-depth 3 https://rdap.nic.com/domain/example.com

# Test with multiple link targets
rdap-test --link-target entity --link-target nameserver https://rdap.nic.com/domain/example.com

# Only show link target results
rdap-test --only-show-target --link-target entity https://rdap.nic.com/domain/example.com

Domain Registry and Registrar Testing

When testing domain-related RDAP servers, you can use link target controls:

# Test domain registry link following
rdap-test --registry https://rdap.nic.com/domain/example.com

# Test domain registrar link following  
rdap-test --registrar https://rdap.nic.com/domain/example.com

These flags will test the RDAP server's ability to handle link following requests for domain registry and registrar relationships.

By default, this command does not follow HTTP redirects unless the --follow-redirects argument is given.

Conformance Checks

Some specification conformance checks are done by this client. Each conformance check is assigned a number. These numerical values may be found here. Additionally, each check is classified into one of the following classes:

Informational
Specification Note
Standards Warning
Standards Error
Cidr0 Extension Error
ICANN Extension Error

The --check-type argument may be used to specify which types of checks will be used in reporting errors.

Checking RDAP Extensions

This command can require the explicit presence of RDAP extensions when performing checks. This is controlled with the following arguments:

-e or --expect-extensions - specifies the extension identifier
-g or --expect-group - specifies an extension group. Group values are "gtld", "nro" and "nro-asn".

By default, this command will issue a Standards Error check if an extension is found that is not registered with the IANA. This check may be suppressed using the -E or --allow-unregistered-extensions argument.

Paging Output

Unlike the rdap command, the rdap-test command does not page output.

Output Format

By default, this command will attempt to determine the output format of the information. If it determines the shell is interactive, output will be in rendered-markdown. Otherwise, the output will be JSON.

You can explicitly control this behavior using the -O command argument or the RDAP_TEST_OUTPUT environment variable (see below).

Use the --json shortcut parameter to set the output type to pretty-compact-json.

Directing Queries To A Specific Server

The rdap-test command will use the RDAP bootstrap files provided by IANA to determine the authoritative server for the information being requested. These IANA files have the "base URLs" for the RDAP servers.

Unlike the rdap command, no explicit base URL can be specified.

Caching

The rdap-test command will cache IANA bootstrap files, but does no caching of RDAP responses.

Logging

The rdap-test command logs errors, warning, and other information on its processing. This can be controlled with the --log-level command argument or the RDAP_TEST_LOG environment variable.

Secure Connections

By default, the rdap-test command will use secure connections. The following arguments and environment variables can be used to modify this behavior:

-T or RDAP_TEST_ALLOW_HTTP : RDAP servers should be using HTTPS. When given or set to true, HTTP will be allowed.
-K or RDAP_TEST_ALLOW_INVALID_HOST_NAMES : Allows HTTPS connections in which the host name does not match the certificate.
-I or RDAP_TEST_ALLOW_INVALID_CERTIFICATES : Allows HTTPS connections in which the TLS certificate is invalid.

Retries and Timeouts

By default, the client will retry queries if given an HTTP 429 response. The following arguments and environmental variables can be used to modify this behavior:

--max-retries or RDAP_MAX_RETRIES: Number of retries to attempt. Default is 1.
--max-retry-secs or RDAP_MAX_RETRY_SECS: Maximum number of seconds to wait before a retry if the retry-after value is greater.
--def-retry-secs or RDAP_DEF_RETRY_SECS: Default number of seconds to wait before a retry if no retry-after value is provided by the server.

The --timeout-secs argument determines the total time the client will wait for an answer.

DNS Resolver

By default, this command will use the public DNS resolver at 8.8.8.8 port 53 to determine the set of RDAP endpoints to test. To change this value, use the --dns-resolver argument.

Configuration

The rdap-test command uses the same configuration techniques and file as the rdap command. However, environment variables are RDAP_TEST_XXXX instead of RDAP_XXXX (where XXXX is a specific variable).

Resetting

Use the rdap command --reset argument to reset all configuration and state. This will remove the IANA caches and reset the rdap.env file (see above) to the default.

RDAP server

RDAP Server

This server was created to aid in the development of the ICANN RDAP Command Line Interface client. It can be used as a library or as a server started within its own process. It currently has in-memory storage, though its storage layer is architected to accommodate a PostgreSQL backend if that is needed in the future.

RDAP query support in this server is as follows:

[X] LDH Domain lookup (/domain/ldh)
[X] IDN U-Label lookup (/domain/unicode)
[X] Entity lookup (/entity/handle)
[X] Nameserver lookup (/nameserver/fqdn)
[X] Autnum lookup (/autnum/123)
[X] IP address lookup (/ip/ip_address)
[X] CIDR lookup (/ip/prefix/len)
[X] Domain search
[ ] Nameserver search
[ ] Entity search
[X] Help (/help)

This server explicityl supports the following extensions:

Cidr0
Exts
JSContact
Redacted
SimpleRedaction

Other extensions, such as object tagging, can be placed in the rdapConformance array of data used in this server.

Additionally, this server can act as an RDAP bootstrap server.

Running the Server

The server is configured via environment variables. These variables can be configured in a shell script or whatever normal means are used to set environment variables. Additionally, they may be placed in a .env in the current directory.

"RDAP_SRV_LOG" - can be the values 'info', 'error', 'debug', 'warn' or 'trace'. Defualts to 'info'.
"RDAP_SRV_LISTEN_ADDR" - the IP address of the interface to listen on. Defaults to 127.0.0.1.
"RDAP_SRV_LISTEN_PORT" - the port to listen on. Defaults to 3000.
"RDAP_SRV_STORAGE" - either "mem" or "pg", but "pg" doesn't do anything.
"RDAP_SRV_DB_URL" - database URL when using "pg" storage.
"RDAP_SRV_DATA_DIR" - the directory containing the files used for storage.

Memory Storage

The data for the memory storage is specified by the "RDAP_SRV_DATA_DIR" environment variable. Files in this directory are either valid RDAP JSON files, or template files containing valid RDAP JSON. Files ending in .json are considered to be RDAP JSON, and files ending in .template are considered to be template files.

Memory storage supports hot reloading. This can be done by "touching" either the file named "update" or "reload" in the data directory. The "update" file triggers an update but does not remove any previous data unless that data exists in the data directory files. The "reload" file triggers a full reload, removing all previous data and replacing it with the data from the files in the data directory.

Alternatively, you can use the rdap-srv-store command to touch the files to trigger reloads and updates: rdap-srv-store --update or rdap-srv-store --reload.

Create Data

RDAP data can often be tricky to create, but the rdap-srv-data command makes it easier. This command does not cover all possible RDAP expressions, but it does cover the common scenarios and can be used as a starting point for those who require more complex RDAP data.

This command has 5 sub-commands, each with its own specific set of command line arguments. Use the --help option to see the arguments for each sub-command.

rdap-srv-data entity --help
rdap-srv-data nameserver --help
rdap-srv-data domain --help
rdap-srv-data autnum --help    
rdap-srv-data network --help

Templates

Template files allow for the creation of many RDAP objects by changing just the ID of the object. The rdap-srv-data command can create a template file which can be used as a template. In other words, one can use the rdap-srv-data command to create the template file and then edit the file with the object ids desired.

The following command creates an entity template using the --template option:

rdap-srv-data --template entity --handle foo --full-name "Bob Smurd"

The IDs array in the templates differ for every object class:

domain: {"ldhName": "foo.example"}. May optionally have a unicodeName as well.
entity: {"handle"; "XXXX"}
nameserver: {"ldhName": "ns.foo.example"}. May optionally have a unicodeName as well.
autnum: {"start_autnum": 1, "end_autnum": 99}
ip: either {"networkId": {"startAddress": "xxx.xxx.xxx.xxx", "endAddress": "xxx.xxx.xxx.xxx"}} or {"networkId": "xxx.xxx.xxx.xxx/yyy"}

Redirects

Template files can also be used to create redirects (which are modeled by the server as RDAP errors though they are not). Like other templates, more than one object ID can be used to create a redirect for many objects.

The following command creates a redirect for an IP network:

rdap-srv-data --redirect http://other.example/ip/11.0.0.0/16 network --cidr 11.0.0.0/16

Use Your Data

As mentioned above, the rdap-srv-store command can be used to signal a reload or update of the server. This command can also be used to copy your own data into the data directory by specifiing a directory:

rdap-srv-store --update /my_data/rdap

This command will perform checks on your data while copying them to ensure the data is RDAP compliant.

Installation

From a Package Manager

Homebrew

The RDAP server is NOT available in ICANN-RDAP Homebrew package.

Arch Linux AUR

Several packages are available in the AUR:

https://aur.archlinux.org/packages?O=0&SeB=nd&K=icann-rdap&outdated=&SB=p&SO=d&PP=50&submit=Go

Pre-Built Binaries

Pre-built binaries are available for most mainstream systems: x86_64 and Arm 64bit for Linux GNU systems, x86_64 and Arm 64bit macOS, and x86_64 for Windows. You may find the pre-built binaries on the Releases page.

For non-Debian-based Linux, compiling from crates.io or source (both are easy) is recommended to avoid issues with dynamic linking to OpenSSL.

Compiling from crates.io

If you have Rust installed on your system, then compiling from source is very straightforward. If you do not have Rust installed on your system, it is usually very easy to do: see Rustup.

If you are on a Linux system, you will need OpenSSL development files. For Debian and Ubuntu, this is usually done via apt install pkg-config libssl-dev. For other Linux systems, consult your packaging documentation.

For macOS and Windows, the native TLS libraries are used, and there are no steps needed to install them.

Compiling from Source

If you have Rust installed on your system, then compiling from source is very straightforward. If you do not have Rust installed on your system, it is usually very easy to do: see Rustup.

If you are on a Linux system, you will need OpenSSL development files. For Debian and Ubuntu, this is usually done via apt install pkg-config libssl-dev. For other Linux systems, consult your packaging documentation.

For macOS and Windows, the native TLS libraries are used, and there are no steps needed to install them.

Run the tests: cargo test

Then build the software: cargo build --release. The executable binaries will be available in the target/release directory.

Quick Start

Create a .env file in the directory where you intend to run the commands, and put the following in that file:

RDAP_SRV_LOG=debug
RDAP_SRV_DATA_DIR=/tmp/rdap-srv/data
RDAP_BASE_URL=http://localhost:3000/rdap

Create directory in /tmp to hold server data files:

mkdir -p /tmp/rdap-srv/data

Create the default server help:

cargo run --bin rdap-srv-data -- srv-help --notice "this is a test server"

NOTE: cargo run makes sure that the code is compiled before running the executable. You may run cargo run --release and access all the executables in the ./target/release directory.

Create some data:

cargo run --bin rdap-srv-data -- entity --handle foo1234 --email joe@example.com --full-name "Joe User"
./target/release/rdap-srv-data nameserver --ldh ns1.example.com --registrant foo1234

Start the server:

cargo run --bin rdap-srv

Query the server with the client in another terminal:

cargo run --bin rdap -- -T -B http://localhost:3000/rdap ns1.example.com

While the server is running, do the following in a separate terminal to add some more data:

cargo run --bin rdap-srv-data -- domain --ldh example.com --registrant foo1234 --ns ns1.example.com
cargo run --bin rdap-srv-store -- --update

Query the server for the new data:

cargo run --bin rdap -- -T -B http://localhost:3000/rdap example.com

For more information on the options available, use the --help option.

Usage

Running the Server

The server is configured via environment variables. These variables can be configured in a shell script or whatever normal means are used to set environment variables. Additionally, they may be placed in a .env in the current directory.

"RDAP_SRV_LOG" - can be the values 'info', 'error', 'debug', 'warn' or 'trace'. Defualts to 'info'.
"RDAP_SRV_LISTEN_ADDR" - the IP address of the interface to listen on. Defaults to 127.0.0.1.
"RDAP_SRV_LISTEN_PORT" - the port to listen on. Defaults to 3000.
"RDAP_SRV_STORAGE" - either "mem" or "pg", but "pg" doesn't do anything.
"RDAP_SRV_DB_URL" - database URL when using "pg" storage.
"RDAP_SRV_DATA_DIR" - the directory containing the files used for storage.

Memory Storage

The data for the memory storage is specified by the "RDAP_SRV_DATA_DIR" environment variable. Files in this directory are either valid RDAP JSON files, or template files containing valid RDAP JSON. Files ending in .json are considered to be RDAP JSON, and files ending in .template are considered to be template files.

Memory storage supports hot reloading. This can be done by "touching" either the file named "update" or "reload" in the data directory. The "update" file triggers an update but does not remove any previous data unless that data exists in the data directory files. The "reload" file triggers a full reload, removing all previous data and replacing it with the data from the files in the data directory.

Alternatively, you can use the rdap-srv-store command to touch the files to trigger reloads and updates: rdap-srv-store --update or rdap-srv-store --reload.

Create Data

RDAP data can often be tricky to create, but the rdap-srv-data command makes it easier. This command does not cover all possible RDAP expressions, but it does cover the common scenarios and can be used as a starting point for those who require more complex RDAP data.

This command has 5 sub-commands, each with its own specific set of command line arguments. Use the --help option to see the arguments for each sub-command.

rdap-srv-data entity --help
rdap-srv-data nameserver --help
rdap-srv-data domain --help
rdap-srv-data autnum --help    
rdap-srv-data network --help

Templates

Template files allow for the creation of many RDAP objects by changing just the ID of the object. The rdap-srv-data command can create a template file which can be used as a template. In other words, one can use the rdap-srv-data command to create the template file and then edit the file with the object ids desired.

The following command creates an entity template using the --template option:

rdap-srv-data --template entity --handle foo --full-name "Bob Smurd"

The IDs array in the templates differ for every object class:

domain: {"ldhName": "foo.example"}. May optionally have a unicodeName as well.
entity: {"handle"; "XXXX"}
nameserver: {"ldhName": "ns.foo.example"}. May optionally have a unicodeName as well.
autnum: {"start_autnum": 1, "end_autnum": 99}
ip: either {"networkId": {"startAddress": "xxx.xxx.xxx.xxx", "endAddress": "xxx.xxx.xxx.xxx"}} or {"networkId": "xxx.xxx.xxx.xxx/yyy"}

Redirects

Template files can also be used to create redirects (which are modeled by the server as RDAP errors though they are not). Like other templates, more than one object ID can be used to create a redirect for many objects.

The following command creates a redirect for an IP network:

rdap-srv-data --redirect http://other.example/ip/11.0.0.0/16 network --cidr 11.0.0.0/16

Use Your Data

As mentioned above, the rdap-srv-store command can be used to signal a reload or update of the server. This command can also be used to copy your own data into the data directory by specifiing a directory:

rdap-srv-store --update /my_data/rdap

This command will perform checks on your data while copying them to ensure the data is RDAP compliant.

JSContact Support

The rdap-srv-data command provides support for generating RDAP entity objects with JSContact format. JSContact is a JSON-based format for contact information that serves as a modern alternative to vCard.

Command Option

When creating RDAP entities using the entity subcommand, you can use the --jscontact flag to represent the entity with JSContact format instead of the traditional vCard format.

rdap-srv-data entity \
  --handle <HANDLE> \
  --base-url <BASE_URL> \
  --jscontact \
  [other entity options...]

Usage Example

# Create an entity with JSContact format
rdap-srv-data entity \
  --handle "ABC123-EXAMPLE" \
  --base-url "https://rdap.example.com" \
  --full-name "John Doe" \
  --email "john.doe@example.com" \
  --voice "+1-555-123-4567" \
  --street "123 Main St" \
  --locality "Anytown" \
  --region "CA" \
  --country-name "United States" \
  --postal-code "12345" \
  --jscontact

Server Configuration

The RDAP server can be configured to automatically convert vCard contacts to JSContact format using the RDAP_SRV_JSCONTACT_CONVERSION environment variable.

Environment Variable

export RDAP_SRV_JSCONTACT_CONVERSION=<conversion_mode>

Conversion Modes

The RDAP_SRV_JSCONTACT_CONVERSION variable accepts three values:

none (default): Do not perform any JSContact conversions
also: Convert vCard to JSContact and include both formats in the response
only: Convert vCard to JSContact and remove the vCard format

Configuration Examples

# Include both vCard and JSContact formats
export RDAP_SRV_JSCONTACT_CONVERSION=also

# Use only JSContact format (no vCard)
export RDAP_SRV_JSCONTACT_CONVERSION=only

# Disable JSContact conversion (default behavior)
export RDAP_SRV_JSCONTACT_CONVERSION=none

RDAP Bootstrap Server

The RDAP server can be configured to operate as a bootstrap server using the RDAP_SRV_BOOTSTRAP environment variable. When enabled, the server automatically downloads IANA RDAP bootstrap files and provides HTTP redirects to direct clients to the appropriate authoritative RDAP services.

Overview

A bootstrap server serves as a single entry point for RDAP queries. Instead of clients needing to know which RDAP server is authoritative for a specific resource, they can query the bootstrap server, which redirects them to the correct service.

Configuration

Enable bootstrap functionality by setting the RDAP_SRV_BOOTSTRAP environment variable:

export RDAP_SRV_BOOTSTRAP=true

Bootstrap Process

When bootstrap mode is enabled, the server performs the following operations:

1. Initial Bootstrap

Downloads IANA RDAP bootstrap files from IANA
Processes the bootstrap data for different resource types
Creates redirect templates for all supported services
Runs once before starting the bootstrap update thread

2. Automatic Updates

Refreshes bootstrap data every 60 seconds
Checks for updated IANA registry files
Updates redirect templates when new data is available
Maintains cached bootstrap files

3. Data Sources

The bootstrap server downloads and processes the following IANA registries:

DNS Bootstrap: Domain name services (TLD delegations) and reverse DNS.
ASN Bootstrap: Autonomous System number services
IPv4 Bootstrap: IPv4 network services including reverse DNS.
IPv6 Bootstrap: IPv6 network services including reverse DNS.
Object Tags: Service provider entity tags

Redirect Behavior

The bootstrap server issues HTTP 307 (Temporary Redirect) responses for all queries, directing clients to the authoritative RDAP service for the requested resource.

Resource Types

Domain Names

GET /domain/example.com HTTP/1.1
Host: bootstrap.rdap.example.com

HTTP/1.1 307 Temporary Redirect
Location: https://registry.example.com/rdap/domain/example.com

IP Networks

GET /ip/203.0.113.0/24 HTTP/1.1
Host: bootstrap.rdap.example.com

HTTP/1.1 307 Temporary Redirect  
Location: https://rir.example.com/rdap/ip/203.0.113.0/24

Autonomous Systems

GET /autnum/64496 HTTP/1.1
Host: bootstrap.rdap.example.com

HTTP/1.1 307 Temporary Redirect
Location: https://rir3.example.com/rdap/autnum/64496

Configuration Options

Environment Variables

# Enable bootstrap functionality
export RDAP_SRV_BOOTSTRAP=true

# Optional: Update storage when bootstrap data changes
export RDAP_SRV_UPDATE_ON_BOOTSTRAP=true

# Required: Data directory for bootstrap files
export RDAP_SRV_DATA_DIR="/var/lib/rdap-srv/data"

Update Behavior

The RDAP_SRV_UPDATE_ON_BOOTSTRAP variable controls how bootstrap updates are handled:

false (default): Triggers data reload without full storage update
true: Performs complete storage update when bootstrap data changes

ICANN RDAP Users Manual

Command Line Tools

Rust Libraries

An RDAP Server

Command Line Client

The rdap Command

Installation

From a Package Manager

Homebrew

Arch Linux AUR

Pre-Built Binaries

Compiling from crates.io

Compiling from Source

Quick Start

Basic Queries

Command Help

Domain Queries

Basic Domain Queries

Simple Domain Lookup

Explicit Domain Type Specification

A-Label Domain Queries

Server Targeting Options

Link Target Parameters for Registry and Registrar

Registry Link Following

Registrar Link Following

Combined with Depth Control

Bootstrap Registry Selection

Explicit Server URL

TLD Queries

IP Address Queries

Basic IP Address Queries

IPv4 Address Lookup

IPv6 Address Lookup

Explicit IP Type Specification

CIDR Block Queries

IPv4 CIDR Queries

IPv6 CIDR Queries

Short CIDR Notation

Reverse DNS Queries

IP Address Reverse DNS

Reverse DNS for CIDR Blocks

Server Targeting Options

Bootstrap Registry Selection

Explicit Server URL

INR Backup Bootstrap

Link Following

Network Hierarchy Link Following

Autonomous System Number (AS Number) Queries

Basic AS Number Queries

Simple AS Number Lookup

Explicit AS Number Type Specification

AS Number Formats

Standard AS Number Format

Numeric-Only Format

Server Targeting Options

Bootstrap Registry Selection

Explicit Server URL

INR Backup Bootstrap

Redaction Handling

Redaction Flags

Highlight Simple Redactions

Show RFC 9537 Redaction Directives

Do Not Simplify RFC 9537 Redactions

Process RFC 9537 Redactions

Redaction Flag Combinations

Environment Variable Configuration

Output Format Control

Overview

Output Format Options

Auto Detection (Default)

Markdown Formats

Rendered Markdown

Plain Text Markdown

JSON Formats

Compact JSON

Pretty JSON

Pretty Compact JSON (Recommended)

JSON with Extra Information

Specialized Formats

gTLD WHOIS Format

The `rdap` Command

The `rdap-test` Command