What's the difference between ogcli update, create, replace and merge?

ogcli is the Operations Manager's powerful command line configuration utility.   ogcli supports a variety operations to set configuration.

ogcli update

Matches an existing configuration item (e.g. a user) by its unique ID (e.g. the username), and updates its configuration settings with the newly specified settings. 

Unlike other operations that set configuration, you only need to specify the settings to update.

For example:

sudo ogcli update user adal <<'END'
  hashed_password="$5$yg2ElweeO6Nl8qOV$RW2YZ2.upWaumaEKkQ38esg3WISta00n8wjQtvas.7/"
END

ogcli create

create is only supported by configuration item that are a member of a list.  To view these, run:

sudo ogcli --list-endpoints | grep create

This operation creates a brand new configuration item (e.g. a user) and appends it to list of configuration items (e.g. the list of users).

For example:

sudo ogcli create user <<'END'
  username="adal"
  description="Ada Lovelace"
  enabled=true
  no_password=false
  ssh_password_enabled=true
  groups[0]="redteam"
  hashed_password="$5$8uMRMtcOB$txjlAmDYKjK/whJTkk5Axje5mABTQDMlIujlYgq5GfA"
END

ogcli replace

This operation matches an existing configuration item (e.g. a user) by that item's unique ID (e.g. the username), and replaces it in its entirely with a new item with the specified settings.  All configuration settings for must be specified.

The item may be a standalone setting (e.g. system/hostname) or a part of a list (e.g. a user in the users list).

For example:

sudo ogcli replace user adal <<'END'
  username="adal"
  description="Acheron Dal"
  enabled=true
  no_password=false
  ssh_password_enabled=true
  groups[0]="blueteam"
  groups[1]="secops"
  hashed_password="$5$PX7zblL5ew2g4dz2$lU097RnkZz7S7P3vB2wGHl8raPnwsZrE6ffQ0qjiyb7"
END

You may also replace a list in its entirety (e.g. all users).  This takes a list of configuration items, deletes all existing items then creates a xnew list as specified.

For example:

sudo ogcli replace users <<'END'
  users[0].username="root"
  users[0].description="Super User"
  users[0].enabled=true
  users[0].no_password=false
  users[0].groups[0]="admin"
  users[0].ssh_password_enabled=false
  users[1].username="adal"
  users[1].description="Ada Lovelace"
  users[1].enabled=true
  users[1].no_password=false
  users[1].ssh_password_enabled=true
  users[1].groups[0]="redteam"
  users[1].hashed_password="$5$8uMRMtcOB$txjlAmDYKjK/whJTkk5Axje5mABTQDMlIujlYgq5GfA"
  users[2].username="robertw"
  users[2].description="Robert W"
  users[2].enabled=true
  users[2].no_password=false
  users[2].ssh_password_enabled=true
  users[2].groups[0]="admin"
  users[2].hashed_password="$5$xZvJjWTe$dT7w9lw5La/8VFLvMyBb0Zr9Ts7.Oxq5QYAYJpnYb7C"
END

.. results in three users: root, adal and robertw.

ogcli merge

merge is only supported by lists of configuration items.  To view these, run:

sudo ogcli --list-endpoints | grep merge

This operation takes a list of configuration items (e.g. one or more users) and incorporates them into any existing list of items.  If an item's unique ID matches an existing item (e.g. same username), the existing item is replaced, otherwise a new item is created.

Existing items that don't match aren't touched.

For example – say our configuration has two existing users, root and robertw, and we run:

sudo ogcli merge users <<'END'
  users[0].username="adal"
  users[0].description="Ada Lovelace"
  users[0].enabled=true
  users[0].no_password=false
  users[0].ssh_password_enabled=true
  users[0].groups[0]="redteam"
  users[0].hashed_password="$5$8uMRMtcOB$txjlAmDYKjK/whJTkk5Axje5mABTQDMlIujlYgq5GfA"
  users[1].username="robertw"
  users[1].description="Robert W"
  users[1].enabled=true
  users[1].no_password=false
  users[1].ssh_password_enabled=true
  users[1].groups[0]="admin"
  users[1].hashed_password="$5$xZvJjWTe$dT7w9lw5La/8VFLvMyBb0Zr9Ts7.Oxq5QYAYJpnYb7C"
END

.. now we have three users: adal is created, robertw is replaced, and root is left untouched.