There are multiple different kinds of configuration that go into getting a
working registry system up and running. Broadly speaking, configuration works in
two ways -- globally, for the entire sytem, and per-TLD. Global configuration is
managed by editing code and deploying a new version, whereas per-TLD
configuration is data that lives in Datastore in
Registry entities, and is
updated by running
nomulus commands without having to deploy a new version.
Here's a checklist of things that need to be configured upon initial installation of the project:
- Create Google Cloud Storage buckets (see the Architecture documentation for more information).
ConfigModule.javaand set project-specific settings such as product name (see below).
- Copy and edit
ProductionRegistryConfigExample.javawith your project-specific settings (see below).
Before getting into the details of configuration, it's important to note that a
lot of configuration is environment-dependent. It is common to see
statements that operate on the current
RegistryEnvironment, and return
different values for different environments. This is especially pronounced in
LOCAL environments, which don't run on App Engine at all.
As an example, some timeouts may be long in production and short in unit tests.
See the Architecture documentation for more details on environments as used by Nomulus.
App Engine configuration
App Engine configuration isn't covered in depth in this document as it is thoroughly documented in the App Engine configuration docs. The main files of note that come pre-configured in Nomulus are:
cron.xml-- Configuration of cronjobs
web.xml-- Configuration of URL paths on the webserver
appengine-web.xml-- Overall App Engine settings including number and type of instances
datastore-indexes.xml-- Configuration of entity indexes in Datastore
queue.xml-- Configuration of App Engine task queues
application.xml-- Configuration of the application name and its services
Cron, web, and queue are covered in more detail in the "App Engine architecture" doc, and the rest are covered in the general App Engine documentation.
If you are not writing new code to implement custom features, is unlikely that
you will need to make any modifications beyond simple changes to
appengine-web.xml. If you are writing new features, it's
likely you'll need to add cronjobs, URL paths, Datastore indexes, and task
queues, and thus edit those associated XML files.
Global configuration is managed through YAML files that are built with and
deployed in the app. The full list of config options and their default values
can be found in the
default-config.yaml file. If you wish to
change any of these values, do not edit this file. Instead, edit the environment
configuration file named
google/registry/config/files/nomulus-config-ENVIRONMENT.yaml, overriding only
the options you wish to change. Nomulus ships with blank placeholders for all
You will not need to change most of the default settings. Here is the subset of
settings that you will need to change for all deployed environments, including
development environments. See
default-config.yaml for a full
description of each option:
appEngine: projectId: # Your App Engine project ID toolsServiceUrl: hostName: tools-dot-PROJECT-ID.appspot.com # Insert your project ID port: 443 gSuite: domainName: # Your G Suite domain name adminAccountEmailAddress: # An admin login for your G Suite account
For fully-featured production environments that need the full range of features
(e.g. RDE, correct contact information on the registrar console, etc.) you will
need to specify more settings. The
contains an exhaustive list of all settings to override.
From a code perspective, all configuration settings ultimately come through the
RegistryConfig class. This includes a Dagger module called
ConfigModule that provides injectable configuration options. Some legacy
configuration options that can be changed in this class include timeout lengths
and buffer sizes for various tasks, email addresses and URLs to use for various
services, more Cloud Storage bucket names, and WHOIS disclaimer text. Currently,
in order to configure custom configuration, you need to copy
make changes to it, and include your new version instead of the default one in
all Dagger components. All of these options will be replaced with YAML
configuration settings in the near future.
OAuth 2 client id configuration
The open source Nomulus release uses OAuth 2 to authenticate and authorize
users. This includes the
nomulus tool when it connects to the system to
execute commands. OAuth must be configured before you can use the
to set up the system.
OAuth defines the concept of a client id, which identifies the application which the user wants to authorize. This is so that, when a user clicks in an OAuth permission dialog and grants access to data, they are not granting access to every application on their computer (including potentially malicious ones), but only to the application which they agree needs access. Each installation of the Nomulus system should have its own client id. The same client id can be used for all environments.
There are three steps to configuration.
Create the client id in App Engine: Go to your project's "Credentials" page in the Developer's Console. Click "Create credentials" and select "OAuth client ID" from the dropdown. In the create credentials window, select an application type of "Other". After creating the client id, return to the main Credentials page and click the download icon to the right of the client id that you just created. This will download a json file called the client secret file.
Copy the client secret file to the proper location: The client secret file is used by the
nomulustool to authenticate itself to the system. The file should be placed in the location specified by the
registryTool.clientSecretFilenameconfiguration parameter. By default, this is
/google/registry/tools/resources/client_secret.json. Don't overwrite the file named
client_secret_UNITTEST.jsonin that same directory; otherwise, the unit tests will break. If you want to use a different client id for each environment, copy all the client secret files to this directory, with a different name, and specify the file path separately in each environment's configuration file.
Add the new client id to the configured list of allowed client ids: The configuration files include an
oAuthsection, which defines a parameter called
allowedOauthClientIds, specifying a list of client ids which are permitted to connect. Get the appropriate client id string from each client secret json file (which is just a json text file) and add it to the list. You will need to rebuild and redeploy the project so that the configuration changes take effect.
Once these steps are taken, the
nomulus tool will use a client id which the
server is configured to accept, and authentication should succeed. Note that
many Nomulus commands also require that the user have App Engine admin
privileges, meaning that the user needs to be added as an owner or viewer of the
App Engine project.
Sensitive global configuration
Some configuration values, such as PGP private keys, are so sensitive that they
should not be written in code as per the configuration methods above, as that
would pose too high a risk of them accidentally being leaked, e.g. in a source
control mishap. We use a secret store to persist these values in a secure
manner, and abstract access to them using the
Keyring interface contains methods for all sensitive configuration values,
which are primarily credentials used to access various ICANN and ICANN-
affiliated services (such as RDE). These values are only needed for real
production registries and PDT environments. If you are just playing around with
the platform at first, it is OK to put off defining these values until
necessary. To that end, a
DummyKeyringModule is included that simply provides
InMemoryKeyring populated with dummy values for all secret keys. This
allows the codebase to compile and run, but of course any actions that attempt
to connect to external services will fail because none of the keys are real.
To configure a production registry system, you will need to write a replacement
DummyKeyringModule that loads the credentials in a secure way, and
provides them using either an instance of
InMemoryKeyring or your own custom
Keyring. You then need to replace all usages of
DummyKeyringModule with your own module in all of the per-service components
in which it is referenced. The functions in
PgpHelper will likely prove useful
for loading keys stored in PGP format into the PGP key classes that you'll need
to provide from
Keyring, and you can see examples of them in action in
Registry entities, which are persisted to Datastore, are used for per-TLD
configuration. They contain any kind of configuration that is specific to a TLD,
such as the create/renew price of a domain name, the pricing engine
implementation, the DNS writer implementation, whether escrow exports are
enabled, the default currency, the reserved label lists, and more. The
nomulus update_tld command is used to set all of these options. See the admin tool
documentation for more information, as well as the
command-line help for the
update_tld command. Unlike global configuration
above, per-TLD configuration options are stored as data in the running system,
and thus do not require code pushes to update.