Command Line Interface Reference

mrg list experiments

mrg li e

Introduction

The command line interface to Merge, named mrg, lets users interact with a single Merge Portal. To use most commands, users must first login to the testbed and authenticate against an existing active account. The exception for this is account registration when, of course, one cannot authenticate using an active account as it does not exist. Once authenticated, the following commands are available (as of version v1.1.15):

The MergeTB CLI Tool

Usage:
  mrg [command]

Available Commands:
  activate      Activate a user or organization
  compile       Compile a model. Return success or compile error stack on failure.
  completion    Generate the autocompletion script for the specified shell
  config        Manage CLI configuration
  delete        Delete things
  dematerialize Dematerialize a realization
  facility      Facility specific commands
  freeze        Freeze a user or organization
  harbor        Harbor management
  help          Help about any command
  init          Initialize a user
  list          List things
  login         Log in to a portal
  logout        Logout the currently logged in user from the portal
  materialize   Materialize a realization
  membership    Membership commands
  new           Make new things
  nodes         Manage experimental nodes
  pools         Pool specific commands
  push          Push a model to the given experiment repository
  realize       Realize an experiment
  register      Register a new identity with the portal
  relinquish    Relinquish a realization
  show          Show information about things
  unregister    Unregister an existing identity from the portal
  update        Update existing things
  whoami        Show the identity of the logged in user
  xdc           XDC tools

Flags:
  -c, --colorless         Disable color output
  -h, --help              help for mrg
  -j, --json              Output JSON
  -l, --loglevel string   Level to log at. One of panic, fatal, error, warning, info, debug, trace (default "info")
  -s, --server string     MergeTB API server address
  -v, --version           version for mrg

Use "mrg [command] --help" for more information about a command.

All commands support a -h or --help argument which shows the usage and help for that specific command.

At execution all commands have a policy applied before they are executed. Based on the account privileges of the user running the command the action will be allowed or denied. Most commands also are aware of the caller’s data in the system. For instance, when listing projects via mrg list projects, only the callers projects will be listed. Other data returned from a call may be filtered to match the security level of the user and the data accessed.

Accounts

Register

To use Merge, an account is needed. To register for an account use the register command.

Usage

$ mrg register --help
Register a new identity with the portal

Usage
  mrg register <username> <email> <institution> <category> [flags]

Flags:
      --country string             user country
  -h, --help                       help for register
  -n, --name string                user full name
  -o, --organization string        request organization membership
  -r, --organization_role string   request organization role (one of Member,Maintainer,Creator) (default "Member")
  -p, --passwd string              user password
      --usstate string             user US state

Global Flags:
  -c, --colorless         Disable color output
  -j, --json              Output JSON
  -l, --loglevel string   Level to log at. One of panic, fatal, error, warning, info, debug, trace (default "info")
  -s, --server string     MergeTB API server address

To register an account the following are required: username, full name, user institution, an account category, a password, and the user’s country. (If the user’s country is the United States, then a US State is also needed.)

Example

mrg register olive olive@example.com "University of San Francisco" "Graduate student" --name "Olive Oyl" --country "United States" --usstate California -p 123abc!

If the password is not given, mrg will prompt for it.

The list of institutions and user categories are specific to a Merge portal installation. To see the list of available entries, use the commands mrg list portal institutions and mrg list portal user-categories. (These commands do not require authentication.) If a required argument is left blank or is unacceptable, mrg will list the available options. For example here is the output when XXXX is given as a user category:

$ mrg register olive olive@example.com CENIC XXXX --name "Olive Oyl" --country Albania -p abc123!
Error:      InvalidArgument
Message:    User category must be one of Other or Graduate student, Professor, Researcher/Scientist, Teaching assistant, Undergraduate student

Other is usually configured to be an acceptable argument as well, but it depends on the Merge portal administration configuring it to be so.

Once an account is registered, the Merge portal operators need to approve and active the account.

Login

Logging into a Merge portal is done, as one would think, via the login command. This takes the username and password of the account. If the password is not given, mrg will prompt for it. On success, a time-limited token will be granted to the user. While the token is active, all other commands can be run.

Usage

$ mrg login --help
Log in to a portal

Usage:
  mrg login <username> [flags]

Flags:
  -h, --help            help for login
      --nokeys          Do not copy merge generated keys and certificate into ~/.ssh
  -p, --passwd string   User password

Global Flags:
  -c, --colorless         Disable color output
  -j, --json              Output JSON
  -l, --loglevel string   Level to log at. One of panic, fatal, error, warning, info, debug, trace (default "info")
  -s, --server string     MergeTB API server address

Example

$ mrg login olive
Enter password for olive:
$

No response indicates success.

A failure:

$ mrg login olive -p notcorrect
Error:      PermissionDenied
Message:    The provided credentials are invalid, check for spelling mistakes in your password or username, email address, or phone number.

Experiments

Listing

mrg list experiments

Example:

$ mrg list exp
Name.Project          Description    Mode
------------          -----------    ----
experiment.project                   Public
exp.glawler                          Public
bbb.glawler                          Public
eee.glawler                          Public

Showing

mrg show experiment <name>.<project>

Usage:

Show an experiment

Usage:
  mrg show experiment <experiment>.<project> [flags]

Flags:
  -h, --help          help for experiment
  -m, --with-models   Save models for each revision
  -S, --with-status   Show compilation status for each revision

Example:

$ mrg show experiment experiment.project
Repo: https://git.sphere-testbed.net/project/experiment
Mode: Public
Description:
Creator: glawler
Maintainers:
Realizations:
  Revision                                    Realizations
  --------                                    ------------
  9eabb626da475f542bf4002cc2d9d1c448f6cafa    rlz.experiment.project
  d3da9590bbc8bedcb6c494ca6d84b57edb1aa9d6    (none)

Models

A model is an experiment topology and is read from an experiment’s git repository. The model syntax is documented here.

Compiling

A model can be compiled before pushing to an experiment repository via the compile command. If successful the compiled model will be printed to standard out. On failure the compilation errors will.

Note that this does not push the model to the experiment repository. It is just informational. To push use mrg push or git push.

Compile a model. Return success or compile error stack on failure.

Usage:
  mrg compile <model-file> [flags]

Flags:
  -h, --help    help for compile
  -q, --quiet   Do not show the compiled model on success.

Successful example (-q argument is given to quiet output)

glawler@river:~$ mrg compile -q model.py
glawler@river:~$ echo $?
0

Unsuccessful example:

glawler@river:~$ mrg compile model.py
Title:        MX failed to compile
Detail:       Compiliation Failure
Evidence:     Exception: 'Network' object has no attribute 'Connect'

Timestamp:     2022-02-14 20:04:11.560308413 +0000 UTC m=+5998.900641627

Pushing

A model can be pushed to an experiment via git or mrg. To push via mrg use the mrg push ... command.

Push a model to the given experiment repository.

Usage:
  mrg push <model-file> <experiment>.<project> [flags]

Flags:
      --branch string   Repository branch to push the model to. (default "master")
  -h, --help            help for push
      --tag string      Tag the commit with the given tag.

For example to push the model in ./model.py to the master branch in experiment hello.murphy:

mrg push ./model.py hello.murphy
Push succeeded. Revision: fb90c2aa1a19a07410d39ad373c842e7ee544586

If --tag is given the revision will be tagged with the given tag:

mrg push ./model.py hello.murphy --tag v1.2.1

This creates a git tag on the revision and can be used to realize the model.

Realizations

Realizing

mrg realize <realization>.<experiment>.<project> revision|tag <reference> [flags]

Here <reference> is the git revision or git tag of the source repository you would like to realize. For example to create the realization “henry” with a revision tagged “olive” in the experiment hello in the project murphy:

mrg realize henry.hello.murphy tag olive

The same but using the revision:

mrg realize henry.hello.murphy revision bbd67f119672bc0cedc8fd97476e6aeea7458a6c

Listing

To list all realizations you have access to use list .

mrg list realizations

Example:

$ mrg list realizations
Realization               Nodes    Links    Status
-----------               -----    -----    ------
rlz.experiment.project    5        2        Succeeded

Relinquishing

Relinquishing frees all resources held by a realization. If there is an active materialization associated with the realization it will be dematerialized before the realization is relinquished.

mrg relinquish <realization>.<experiment>.<project>

Showing

mrg show realization <realization>.<experiment>.<project>

Materializations

Listing

mrg list materializations

Showing

mrg show materialization <realization>.<experiment>.<project>

Generating files

mrg nodes generate allows you to generate configurations from a realization, including INI style Ansible inventories and etchosts-style name-to-IP mappings:

mrg nodes generate inventory <realization>.<experiment>.<project>

mrg nodes generate etchosts -p exp- <realization>.<experiment>.<project>

Rebooting/reimaging nodes

mrg nodes reboot allows you to reboot or reimage nodes from a materialization:

mrg nodes reboot <realization>.<experiment>.<project> [<nodes>...]

XDCs

Listing

mrg list xdcs

Attaching

mrg xdc attach <xdc>.<project> <realization>.<experiment>.<project>

Detaching

mrg xdc detach <xdc>.<project>

Configuration

Server/Port

mrg config set port $PORT
mrg config set server $SERVER

Status-Depth

This is relevant to versions of mrg of v1.3.0+.

In Merge, there is a status tree associated with high level tasks (like creating a materialization, an XDC, etc.), as they rely on a number of subtasks to be complete before the high level task is complete.

The status of a level is equal to the “worst” status of its children, so viewing the tree at a high level provides a summary of what’s going on, while viewing the tree at a low level specifically tells you what went wrong.

An example is that if everything except for your nodes in a materialization do not come up, then your materialization is not considered successful until all of your nodes come up.

This displays very nicely in the Webgui as you can click to see more information but is a little trickier to display in the cli.

To emulate this behavior in the cli, you can configure the cli to print at depth that you want to see. Negative numbers wrap around from the end, so -1 means the tasks at the bottom of the tree.

This means that the default value of 0 will act as a summary of the entire object, while something like -1 allows you to see the status of actual specific tasks.

Note that if you use negative numbers other than -1, then you have escape the argument as a flag by doing the following: mrg config set status-depth -- -2.

You can also override it for a specific command with --status-depth.

You can set it with:

# only works if it's positive
mrg config set status-depth $INTEGER

# will work if it's positive or negative
mrg config set status-depth -- $INTEGER

Sync and Async

As of versions of mrg of v1.3.0+, the cli operates synchronously by default.

You can change this configuration by using the following commands:

mrg config set sync
mrg config set async

You can also override this configuration value on a per-command basis by using the following global flags:

--sync
--async

Command Wait

This is relevant to versions of mrg of v1.3.0+.

When operating synchronously, the cli has a limit on how long it waits, the default is 1h. The default is 1h, valid time units are ms, s, m, h.

When the command completes or the specified time elapses, it will print the latest received status. The command is only successful if it completed within the specified amount of time.

When operating asynchronously, this value is set to 0.

You can also override it for a specific command with --syncwait.

You can set it with:

mrg config set command-wait $DURATION