mirror of
https://github.com/google/nomulus
synced 2026-08-15 19:56:08 +00:00
Update some Nomulus documentation (#2970)
This doesn't update everything -- it leaves out some of the more complicated changes (architecture, code-structure, configuration, install, and proxy-setup). Those will require more complete rewrites, so I'm punting them to a future PR.
This commit is contained in:
gbrodman
@@ -3,8 +3,8 @@
|
||||
This document covers the first steps of creating some test entities in a newly
|
||||
deployed and configured testing environment. It isn't required, but it does help
|
||||
gain familiarity with the system. If you have not already done so, you must
|
||||
first complete [installation](./install.md) and [initial
|
||||
configuration](./configuration.md).
|
||||
first complete [installation](./install.md) and
|
||||
[initial configuration](./configuration.md).
|
||||
|
||||
Note: Do not create these entities on a production environment! All commands
|
||||
below use the [`nomulus` admin tool](./admin-tool.md) to interact with the
|
||||
@@ -12,55 +12,30 @@ running registry system. We'll assume that all commands below are running in the
|
||||
`alpha` environment; if you named your environment differently, then use that
|
||||
everywhere that `alpha` appears.
|
||||
|
||||
## Temporary extra steps
|
||||
|
||||
Using the `nomulus` admin tool currently requires two additional steps to enable
|
||||
full functionality. These steps should _not_ be done for a production
|
||||
deployment - a suitable solution for production is in progress.
|
||||
|
||||
Modify the `tools` module `web.xml` file to remove admin-only restrictions.
|
||||
Look for the `<auth-constraint>admin</auth-constraint>` element. Comment out
|
||||
this element, and redeploy the tools module to your live app.
|
||||
|
||||
[app-default-creds]: https://developers.google.com/identity/protocols/application-default-credentials
|
||||
|
||||
## Create a TLD
|
||||
|
||||
Pick the name of a TLD to create. For the purposes of this example we'll use
|
||||
"example", which conveniently happens to be an ICANN reserved string, meaning
|
||||
it'll never be created for real on the Internet at large.
|
||||
it'll never be created for real on the Internet at large. Then,
|
||||
[create a TLD](operational-procedures/modifying-tlds.md) using the
|
||||
[example template](https://github.com/google/nomulus/blob/master/core/src/test/resources/google/registry/tools/tld.yaml)
|
||||
as a guide.
|
||||
|
||||
The fields you'll want to change from the template: * `driveFolderId` should be
|
||||
null * `roidSuffix` should be `EXAMPLE` -- this is the suffix that will be used
|
||||
for repository ids of domains on the TLD. This suffix must be all uppercase and
|
||||
a maximum of eight ASCII characters and can be set to the upper-case equivalent
|
||||
of our TLD name (if it is 8 characters or fewer), such as "EXAMPLE." You can
|
||||
also abbreviate the upper-case TLD name down to 8 characters. Refer to the
|
||||
[gTLD Registry Advisory: Correction of non-compliant ROIDs][roids] for further
|
||||
information. * `tldStr` should be `example` * `tldType` should be `TEST`, which
|
||||
identifies that the TLD is for testing purposes, whereas `REAL` would identify
|
||||
the TLD as a live TLD
|
||||
|
||||
```shell
|
||||
$ nomulus -e alpha create_tld example --roid_suffix EXAMPLE \
|
||||
--initial_tld_state GENERAL_AVAILABILITY --tld_type TEST \
|
||||
--dns_writers VoidDnsWriter
|
||||
[ ... snip confirmation prompt ... ]
|
||||
Perform this command? (y/N): y
|
||||
Updated 1 entities.
|
||||
$ nomulus -e alpha configure_tld --input=example.yaml
|
||||
```
|
||||
|
||||
* `-e` is the environment name (`alpha` in this example).
|
||||
* `create_tld` is the subcommand to create a TLD. The TLD name is "example"
|
||||
which happens to be an ICANN reserved string, and therefore "example" can
|
||||
never be created on the Internet at large.
|
||||
* `--initial_tld_state` defines the initial state of the TLD.
|
||||
`GENERAL_AVAILABILITY`, in the case of our example, allows you to
|
||||
immediately create domain names by bypassing the sunrise and landrush domain
|
||||
registration periods.
|
||||
* `--tld_type` is the type of TLD. `TEST` identifies that the TLD is for
|
||||
testing purposes, where `REAL` identifies the TLD is a live TLD.
|
||||
* `roid_suffix` is the suffix that will be used for repository ids of domains
|
||||
on the TLD. This suffix must be all uppercase and a maximum of eight ASCII
|
||||
characters and can be set to the upper-case equivalent of our TLD name (if
|
||||
it is 8 characters or fewer), such as "EXAMPLE." You can also abbreviate the
|
||||
upper-case TLD name down to 8 characters. Refer to the [gTLD Registry
|
||||
Advisory: Correction of non-compliant ROIDs][roids] for further information.
|
||||
* `--dns_writers` is the list of DNS writer modules that specify how changes
|
||||
to domains for the TLD are communicated to actual DNS servers. We use
|
||||
`VoidDnsWriter` in this case so as to not have to set up DNS. Typically
|
||||
one might use CloudDnsWriter (for Google Cloud DNS) or implement your own
|
||||
solution.
|
||||
|
||||
## Create a registrar
|
||||
|
||||
Now we need to create a registrar and give it access to operate on the example
|
||||
@@ -96,36 +71,6 @@ Where:
|
||||
* `--allowed_tlds` is a comma-delimited list of top level domains where this
|
||||
registrar has access.
|
||||
|
||||
## Create a contact
|
||||
|
||||
Now we want to create a contact, as a contact is required before a domain can be
|
||||
created. Contacts can be used on any number of domains across any number of
|
||||
TLDs, and contain the information on who owns or provides technical support for
|
||||
a TLD. These details will appear in WHOIS queries.
|
||||
|
||||
```shell
|
||||
$ nomulus -e alpha create_contact -c acme --id abcd1234 \
|
||||
--name 'John Smith' --street '234 Fake St' --city 'North Fakington' \
|
||||
--state MA --zip 23456 --cc US --email jsmith@e.mail
|
||||
[ ... snip EPP response ... ]
|
||||
```
|
||||
|
||||
Where:
|
||||
|
||||
* `create_contact` is the subcommand to create a contact.
|
||||
* `-c` is used to define the registrar. The `-c` option is used with most
|
||||
`registry_tool` commands to specify the id of the registrar executing the
|
||||
command. Contact, domain, and host creation all work by constructing an EPP
|
||||
message that is sent to the registry, and EPP commands need to run under the
|
||||
context of a registrar. The "acme" registrar that was created above is used
|
||||
for this purpose.
|
||||
* `--id` is the contact id, and is referenced elsewhere in the system (e.g.
|
||||
when a domain is created and the admin contact is specified).
|
||||
* `--name` is the display name of the contact, which is usually the name of a
|
||||
company or of a person.
|
||||
|
||||
The address and `email` fields are required to create a contact.
|
||||
|
||||
## Create a host
|
||||
|
||||
Hosts are used to specify the IP addresses (either v4 or v6) that are associated
|
||||
@@ -156,8 +101,7 @@ To tie it all together, let's create a domain name that uses the above contact
|
||||
and host.
|
||||
|
||||
```shell
|
||||
$ nomulus -e alpha create_domain fake.example --client acme --admins abcd1234 \
|
||||
--techs abcd1234 --registrant abcd1234 --nameservers ns1.google.com
|
||||
$ nomulus -e alpha create_domain fake.example --client acme --nameservers ns1.google.com
|
||||
[ ... snip EPP response ... ]
|
||||
```
|
||||
|
||||
@@ -166,26 +110,19 @@ Where:
|
||||
* `create_domain` is the subcommand to create a domain name. It accepts a
|
||||
whitespace-separated list of domain names to be created
|
||||
* `--client` is used to define the registrar.
|
||||
* `--admins` is the administrative contact's id(s).
|
||||
* `--techs` is the technical contact's id(s).
|
||||
* `--registrant` is the registrant contact's id.
|
||||
* `--nameservers` is a comma-separated list of hosts.
|
||||
|
||||
Note how the same contact id is used for the administrative, technical, and
|
||||
registrant contact. It is common for domain names to use the same details for
|
||||
all contacts on a domain name.
|
||||
## Verify test entities using RDAP
|
||||
|
||||
## Verify test entities using WHOIS
|
||||
|
||||
To verify that everything worked, let's query the WHOIS information for
|
||||
To verify that everything worked, let's query the RDAP information for
|
||||
fake.example:
|
||||
|
||||
```shell
|
||||
$ nomulus -e alpha whois_query fake.example
|
||||
[ ... snip WHOIS response ... ]
|
||||
$ nomulus -e alpha rdap_query fake.example
|
||||
[ ... snip RDAP response ... ]
|
||||
```
|
||||
|
||||
You should see all of the information in WHOIS that you entered above for the
|
||||
contact, nameserver, and domain.
|
||||
You should see all the information in RDAP that you entered above for the
|
||||
nameserver and domain.
|
||||
|
||||
[roids]: https://www.icann.org/resources/pages/correction-non-compliant-roids-2015-08-26-en
|
||||
|
||||
Reference in New Issue
Block a user