diff --git a/docs/install.md b/docs/install.md index 2a254aa36..e98632a65 100644 --- a/docs/install.md +++ b/docs/install.md @@ -120,3 +120,128 @@ Then, use `appcfg` to [deploy the WAR files](https://cloud.google.com/appengine/ $ /path/to/appcfg.sh update /path/to/registry_default.war $ /path/to/appcfg.sh update /path/to/registry_backend.war $ /path/to/appcfg.sh update /path/to/registry_tools.war + +## Creating test entities + +Once the code is deployed, the next step is to play around with creating some +entities in the registry, including a TLD, a registrar, a domain, a contact, and +a host. Note: Do this on a non-production environment! All commands below use +`registry_tool` to interact with the running registry system; see the +documentation on `registry_tool` for additional information on it. 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. + +### 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. + + $ registry_tool -e alpha create_tld example --roid_suffix EXAMPLE \ + --initial_tld_state GENERAL_AVAILABILITY --tld_type TEST + [ ... snip confirmation prompt ... ] + Perform this command? (y/N): y + Updated 1 entities. + +The name of the TLD is the main parameter passed to the command. The initial +TLD state is set here to general availability, bypassing sunrise and landrush, +so that domain names can be created immediately in the following steps. The TLD +type is set to `TEST` (the other alternative being `REAL`) for obvious reasons. + +`roid_suffix` is the suffix that will be used for repository ids of domains on +the TLD -- it must be all uppercase and a maximum of eight ASCII characters. +ICANN +[recommends](https://www.icann.org/resources/pages/correction-non-compliant-roids-2015-08-26-en) +a unique ROID suffix per TLD. The easiest way to come up with one is to simply +use the entire uppercased TLD string if it is eight characters or fewer, or +abbreviate it in some sensible way down to eight if it is longer. The full repo +id of a domain resource is a hex string followed by the suffix, +e.g. `12F7CDF3-EXAMPLE` for our example TLD. + +### Create a registrar + +Now we need to create a registrar and give it access to operate on the example +TLD. For the purposes of our example we'll name the registrar "Acme". + + $ registry_tool -e alpha create_registrar acme --name 'ACME Corp' \ + --registrar_type TEST --password hunter2 \ + --icann_referral_email blaine@acme.example --street '123 Fake St' \ + --city 'Fakington' --state MA --zip 12345 --cc US --allowed_tlds example + [ ... snip confirmation prompt ... ] + Perform this command? (y/N): y + Updated 1 entities. + Skipping registrar groups creation because only production and sandbox + support it. + +In the command above, "acme" is the internal registrar id that is the primary +key used to refer to the registrar. The `name` is the display name that is used +less often, primarily in user interfaces. We again set the type of the resource +here to `TEST`. The `password` is the EPP password that the registrar uses to +log in with. The `icann_referral_email` is the email address associated with +the initial creation of the registrar -- note that the registrar cannot change +it later. The address fields are self-explanatory (note that other parameters +are available for international addresses). The `allowed_tlds` parameter is a +comma-delimited list of TLDs that the registrar has access to, and here is set +to the example TLD. + +### 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. Note the `-c` parameter, +which stands for client identifier: This is used on most `registry_tool` +commands, and is used to specify the id of the registrar that the command will +be executed using. 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. + + $ registry_tool -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 ... ] + +The `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). The `name` is the +display name of the contact, which is usually the name of a company or of a +person. Again, the address fields are required, along with an `email`. + +### Create a host + +Hosts are used to specify the IP addresses (either v4 or v6) that are associated +with a given nameserver. Note that hosts may either be in-bailiwick (on a TLD +that this registry runs) or out-of-bailiwick. In-bailiwick hosts may +additionally be subordinate (a subdomain of a domain name that is on this +registry). Let's create an out-of-bailiwick nameserver, which is the simplest +type. + + $ my_registry_tool -e alpha create_host -c acme --host ns1.google.com + [ ... snip EPP response ... ] + +Note that hosts are required to have IP addresses if they are subordinate, and +must not have IP addresses if they are not subordinate. Use the `--addresses` +parameter to set the IP addresses on a host, passing in a comma-delimited list +of IP addresses in either IPv4 or IPv6 format. + +### Create a domain + +To tie it all together, let's create a domain name that uses the above contact +and host. + + $ registry_tool -e alpha create_domain -c acme --domain fake.example \ + --admin abcd1234 --tech abcd1234 --registrant abcd1234 \ + --nameservers ns1.google.com + [ ... snip EPP response ... ] + +Note how the same contact id (from above) is used for the administrative, +technical, and registrant contact. This is quite common on domain names. + +To verify that everything worked, let's query the WHOIS information for +fake.example: + + $ registry_tool -e alpha whois_query fake.example + [ ... snip WHOIS response ... ] + +You should see all of the information in WHOIS that you entered above for the +contact, nameserver, and domain.