moctl

Name

moctl — administer Moera nodes

Synopsis

moctl [-h] [-d] [-H URL | -N NAME] [-k]
      [-s URL] [-S SECRET]
      [-P PROVIDER] [-T TOKEN]
      [-V] OBJECT COMMAND ...

Options

-h, --help

Get the list of all available options, their meaning, and their short and long forms.

-V, --version

Show the program’s version number and exit.

-d, --dev

Use the development naming server to resolve node names.

-s URL, --naming-server URL

Use the provided naming server to resolve node names.

-H URL, --host URL

-N NAME, --name NAME

Manage the node designated by the given URL or NAME. These options are mutually exclusive.

These options define the node to be managed by all commands, except domain creation/deletion commands. For domain creation/deletion commands, these options define the node for sending API requests to.

-k, --insecure

Disable SSL certificate verification for HTTPS connections to the naming server and the node.

Use this option only when connecting to a trusted server with a self-signed or otherwise untrusted certificate.

-S SECRET, --root-secret SECRET

Define root admin secret used for authentication.

-T TOKEN, --token TOKEN

Define the admin token used for authentication.

-P PROVIDER, --provider PROVIDER

Use the provider defined in the configuration file. It is recommended to use the configuration file to store tokens and secrets instead of passing them through the command line. Command-line options override the defaults set in the configuration file.

If the provider is not set explicitly, the program uses the node address passed in -H/-N options to find the first provider that has domain= defined and the node is located on one of its subdomains. For example, if the node is lamed.moera.blog, the provider having domain = moera.blog fits the criteria.

If no provider is found by domain name, the first provider in the configuration file is used.

OBJECT

The object to be managed. Each object has a set of COMMANDs defined for it. Use -h to get the list of commands for a particular object (moctl domain -h) and the list of command-specific options for a particular command (moctl domain create -h).

The available objects are (you can use a full or short name):

• domain (dom) — manage domains (nodes located on the same server)
• credentials (cr) — manage credentials
• name (nm) — manage node name
• malware (mal) — manage malware hashes
• token (t) — manage authentication tokens
• option (op) — change settings

The commands are described in the following sections.

Most commands that modify node state require authentication. Depending on the operation, use either a root admin secret (-S) or an admin token (-T). token create is the main exception: it authenticates with the current admin password passed as a positional argument.

Manage domains

These commands manage domains — nodes located on the same server. Usually they have domain names that are subdomains of the same domain, but this is not required.

domain list

List all domains (nodes) defined on the server.

domain show

Show the detailed information about the domain. (The domain is defined by -H/-N options.)

domain create DOMAIN

Create a domain with the given domain name.

domain delete DOMAIN

Delete a domain with the given domain name.

Manage credentials

These commands manage credentials used to authenticate the owner (admin) of the node.

credentials check

Check and display whether admin credentials are set for the node.

credentials set-password PASSWORD

Set the admin password for the node. If the node has an admin password defined, this operation fails.

credentials delete-password

Delete the admin password of the node. Without a password, the node can be taken over by anybody, so a new password should be set as soon as possible.

credentials get-email

Display node owner’s e-mail address, if set.

credentials set-email ADDRESS

Set node owner’s e-mail address.

Manage node name

These commands manage the node name stored on the node. The commands do not make any changes on the naming server — the node itself updates the naming server when needed.

name show

Show the node name.

name status

Display the status of the last operation on the name.

name register NAME

Register a new name NAME and assign it to the node. The command outputs the 24 secret words that are needed to control the name.

name assign NAME

Assign an existing name NAME to the node. The 24 secret words are to be passed to the standard input, one per line. It is allowed to pass them exactly as they are printed by name register, where each word is prepended with its number. These numbers are ignored.

name delete

Remove name information from the node.

Manage malware hashes

These commands manage the malware user list on the node. Each hash is stored in the list as node_name.

malware add HASH

Add HASH to the malware list.

malware delete HASH

Delete HASH from the malware list.

malware show HASH

Show HASH and its creation timestamp, separated by a tab. If HASH is not found, print nothing.

Manage authentication tokens

These commands manage tokens that are used to authenticate as administrator on the node. The token ID is used to identify the particular token in later commands.

token list

List all tokens available on the node. Each line contains the token ID and either the token name or, for unnamed tokens, the token value itself. If the token belongs to a plugin, the plugin name is shown in a third column.

token show ID

Show the detailed information about the token with the given ID, including the token value, permissions, timestamps, and last-use information when available.

token create [-n NAME] [-p PERMISSIONS] PASSWORD

Create a new token using the current admin PASSWORD. This command authenticates with the password directly and does not require -T or -S.

-n NAME, --token-name NAME

The name to be assigned to the token. If not set, the token becomes unnamed.

-p PERMISSIONS, --permissions PERMISSIONS

Comma-separated list of permissions to be assigned to the token.

token update [-n NAME] [-p PERMISSIONS] ID

Change the token’s name or permissions and print the updated token details.

-n NAME, --token-name NAME

Assign a human-readable name to the token.

-p PERMISSIONS, --permissions PERMISSIONS

Comma-separated list of permissions to be assigned to the token.

token delete ID

Delete the token.

Change settings

These commands are used to display or change node settings (options). The node admin may change regular settings, while changing privileged settings or default values requires root admin authentication.

option show [-d] [--defaults] [-m] [--prefix PREFIX] [-t]

List all available settings. Letter P in the first column means that the setting is privileged (can be changed by the root admin only). * in the second column means that the setting was modified (i.e., holds a non-default value).

-d, --description

Show descriptions of the settings’ meaning.

--defaults

Show the default values of the settings instead of the current values.

-m, --modified

Show only the settings that were modified.

--prefix PREFIX

Show only the settings having names starting with PREFIX.

-t, --type

Show information about the settings’ type.

option set NAME VALUE

Set the setting NAME to the given VALUE.

option reset NAME

Reset the setting NAME to its default value.

option set-default NAME VALUE

Set default value of the setting NAME to the given VALUE.

option reset-default NAME

Reset default value of the setting NAME to its built-in value.

option set-privileged NAME

Make the setting NAME privileged.

option set-not-privileged NAME

Make the setting NAME not privileged.

option reset-privileged NAME

Reset privileged status of the setting NAME to its built-in value.