google-nomulus/docs/admin-tool.md

Admin tool

Nomulus includes a command-line registry administration tool that is invoked using the nomulus command. It has the ability to view and change a large number of things in a live Nomulus environment, including creating registrars, updating premium and reserved lists, running an EPP command from a given XML file, and performing various backend tasks like re-running RDE if the most recent export failed. Its code lives inside the tools package (java/google/registry/tools), and is compiled by building the nomulus target in the Bazel BUILD file in that package.

The tool connects to the Google Cloud Platform project (identified by project ID) that was configured in your implementation of RegistryConfig when the tool was built. See the configuration guide for more information. The tool can switch between project IDs that represent different environments within a single overall platform (i.e. the production environment plus development and testing environments); see the -e parameter below. For example, if the platform is called "acme-registry", then the production project ID is also "acme-registry", and the project ID for the sandbox environment is "acme-registry-sandbox".

Build the tool

To build the nomulus tool, execute the following bazel build command inside any directory of the codebase. You must rebuild the tool any time that you edit configuration or make database schema changes.

$ bazel build //java/google/registry/tools:nomulus

It's recommended that you alias the compiled binary located at bazel-genfiles/java/google/registry/nomulus (or add it to your shell path) so that you can run it easily. The rest of this guide assumes that it has been aliased to nomulus.

Running the tool

The registry tool is always called with a specific environment to run in using the -e parameter. This looks like:

$ nomulus -e production {command name} {command parameters}

You can get help about the tool in general, or about a specific subcommand, as follows:

$ nomulus -e alpha --help # Lists all subcommands
$ nomulus -e alpha SUBCOMMAND --help # Help for a specific subcommand

Note that the documentation for the commands comes from JCommander, which parses metadata contained within the code to yield documentation.

Local and server-side commands

There are two broad ways that commands are implemented: some that send requests to ToolsServlet to execute the action on the server (these commands implement ServerSideCommand), and others that execute the command locally using the Remote API (these commands implement RemoteApiCommand). Server-side commands take more work to implement because they require both a client and a server-side component. However, they are fully capable of doing anything that is possible with App Engine, including running a large MapReduce, because they execute on the tools service in the App Engine cloud.

Local commands, by contrast, are easier to implement, because there is only a local component to write, but they aren't as powerful. A general rule of thumb for making this determination is to use a local command if possible, or a server-side command otherwise.

Common tool patterns

All tools ultimately implement the Command interface located in the tools package. If you use an integrated development environment (IDE) such as IntelliJ to view the type hierarchy of that interface, you'll see all of the commands that exist, as well as how a lot of them are grouped using sub-interfaces or abstract classes that provide additional functionality. The most common patterns that are used by a large number of other tools are:

• BigqueryCommand -- Provides a connection to BigQuery for tools that need it.
• ConfirmingCommand -- Provides the methods prompt() and execute() to override. prompt() outputs a message (usually what the command is going to do) and prompts the user to confirm execution of the command, and then execute() actually does it.
• EppToolCommand -- Commands that work by executing EPP commands against the server, usually by filling in a template with parameters that were passed on the command-line.
• MutatingEppToolCommand -- A sub-class of EppToolCommand that provides a --dry_run flag, that, if passed, will display the output from the server of what the command would've done without actually committing those changes.
• GetEppResourceCommand -- Gets individual EPP resources from the server and outputs them.
• ListObjectsCommand -- Lists all objects of a specific type from the server and outputs them.
• MutatingCommand -- Provides a facility to create or update entities in the database, and uses a diff algorithm to display the changes that will be made before committing them.