Myrmex CLI

Last Updated 10/11/2021, 10:53:38 AM UTC
About 10 min read

Use the myrmex CLI to manage and automate monitoring operations locally or remotely over SSH.

# Usage

To list the available commands, run myrmex without any parameters or execute myrmex help

$ myrmex
NAME:
   myrmex - controls myrmex server locally or over ssh

USAGE:
   myrmex [global options] command [command options] [arguments...]

VERSION:
   2.2.0

DESCRIPTION:
   myrmex cli

COMMANDS:
   agent         manage agents
   collector     manage agent collectors
   action        manage agent action plugins
   autoconf      auto configure collectors, actions and alerts
   maintenance   executes maintenance actions
   admin         manage access control
   security      manages security
   auxdata       work with aux data
   autocomplete  manages shell autocompletion for this program
   help, h       Shows a list of commands or help for one command

GLOBAL OPTIONS:
   --host value, -H value  the local or remote myrmex server to connect to [$MYRMEX_HOST, $POLARIS_HOST, $MYRMEX_HOME, $POLARIS_HOME]
   --help, -h              show help
   --version, -v           print the version

COPYRIGHT:
   Arisant, LLC (2018)

To show help information for a command or subcommand use --help. For example:

$ myrmex agent --help
NAME:
   myrmex agent - manage agents

USAGE:
   myrmex agent command [command options] [arguments...]

COMMANDS:
   ls       lists registered agents
   eject    ejects an agent        
   readmit  readmits an agent

OPTIONS:
   --help, -h  show help

$ myrmex agent ls --help
NAME:
   myrmex agent ls - lists registered agents

USAGE:
   myrmex agent ls [command options] [arguments...]

OPTIONS:
   --format value  formats the output using go templates
   --filter value  filters output based on provided conditions
   --ejected       lists ejected agents

# Command Autocompletion

The CLI supports bash auto completion for all its commands, subcommands and options so that you do not have to look up usage with --help. To auto complete hit TAB anywhere on the commands line after the myrmex command. Enable this feature with:

sudo myrmex autocomplete install-bash

# Connect to a `myrmex` server

You can use the CLI to manage local or remote (over SSH) myrmex servers. Specify the server installation directory (host) you want to connect to using one of the following ways:

the -H, --host flag
one of the following environment variables (in order of precedence)
- MYRMEX_HOST
- POLARIS_HOST
- MYRMEX_HOME
- POLARIS_HOME

If you have a myrmex installation at /home/myrmex/server on node some-node.com the you can connect to it locally in any one of these ways:

# absolute path of installation
myrmex -H /home/myrmex/server agent ls
# relative path of installation from current working directory /home/myrmex
myrmex -H server agent ls
# local via env variable
export MYRMEX_HOST=/home/myrmex/server
myrmex agent ls
unset MYRMEX_HOST
export POLARIS_HOST=/home/myrmex/server
myrmex agent ls

# Remote connection over SSH

SSH on Windows

Windows Server 2019/Windows 10 and higher natively support ssh client (opens new window) with all it's standard tool chain (ssh-agent, etc). You may also consider using WSL-1 (opens new window) and Microsoft Windows Terminal (opens new window).

You can manage a remote myrmex installation over SSH by setting the installation directory flag or env vars to ssh://<user>@host[<:port>]/<myrmex/installation/dir>. For example:

# absolute path of installation
myrmex -H ssh://me@some-node.com/home/myrmex/server agent ls
# env variable
export MYRMEX_HOST=ssh://me@some-node.com/home/myrmex/server
myrmex agent ls
unset MYRMEX_HOST
export POLARIS_HOST=ssh://me@some-node.com/home/myrmex/server
myrmex agent ls

The CLI tries to authenticate using the none, publickey, password methods in this order. If ssh-agent is up, it will exclusively use it to fetch keys. If not then it will use the default key $HOME/.ssh/id_rsa and ask you for it's passphrase. To add your SSH keys to ssh-agent:

ssh-add -t 1h ~/.ssh/my_key

IMPORTANT

The default lifetime of identities added to ssh-agent by ssh-add is indefinite. This is not a good security practice, you should limit this lifetime with the -t flag and create an alias for ssh-add with your desired lifetime; e.g. alias ssh-add="ssh-add -t 1h".

# Output filtering and formatting

Commands that take the --filter option allow you to filter the command output. The format is key=value. If there is more than one filter, then use repeated --filter options (e.g. --filter "key1=value1" --filter "key2=value2"). The --format option allow you to format the command output using Go templates (opens new window).

The filter keys and format placeholders depend on the command context, use

myrmex COMMAND --format "{{.}}"

to see the available keys and placeholders.

Output filtering and formatting allow you to automate tasks by creating command pipelines. For example, here's how to pause all sys-mon tasks on all agents in one go:

$ for uuid in $(myrmex collector ls -filter "pluginName=sys-mon" --format "{{.UUID}}")
> do
> myrmex collector pause $uuid
> done

# myrmex agent

Manage agents

Command	Description
`ls`	list registered agents
`eject`	eject an agent from the system
`readmit`	readmit an ejected agent

# Examples

List all agents

$ myrmex agent ls
ID                                      HOST                    REMOTE ADDR                                     STATUS  MTLS CERT       MTLS CERT EXPIRES
-----------------------------------------------------------------------------------------------------------------------------------------------------------
f38755bf-bad7-1489-54a1-d9edbf49a4be    api01                   api01.app.example.com                           Online  active          2021-12-12T01:26:00-06:00
81a18615-1da1-e0e6-f171-81c659b0310c    api02                   api02.app.example.com                           Offline active          2021-11-26T20:06:00-06:00
72adf789-299c-7e0b-d6a5-bf2ea3a2dce9    db1                     catdb1.db.example.com                           Online  active          2021-12-30T20:17:00-06:00
58d6d260-831e-c257-ccc7-7374f38e52fe    db2                     198.51.100.13                                   Online  active          2021-12-29T04:07:00-06:00
da125baf-9543-4156-f491-735400d5a717    finance                 finance.app.example.com                         Online  active          2021-11-02T15:42:00-05:00

List offline agents

$ myrmex agent ls --filter "status=Offline" 
ID                                      HOST                    REMOTE ADDR                                     STATUS  MTLS CERT       MTLS CERT EXPIRES
-----------------------------------------------------------------------------------------------------------------------------------------------------------
81a18615-1da1-e0e6-f171-81c659b0310c    api02                   api02.app.example.com                           Offline active          2021-11-26T20:06:00-06:00

List ejected agents

$ myrmex agent ls --ejected
AGENT ID                                LAST KNOWN ADDR
-------------------------------------------------------------------------------------
669dbe16-5c21-ffa4-2ff4-30580571ed80    api04.app.example.com

Eject an agent

myrmex agent eject 58d6d260-831e-c257-ccc7-7374f38e52fe

Readmit an agent

myrmex agent readmit 58d6d260-831e-c257-ccc7-7374f38e52fe

# myrmex collector

Manages collector tasks

Command	Description
`ls`	list collector tasks
`cat`	shows the configuration file for a task
`cat-config-file`	shows a collector configuration file by path
`start`	start a task
`pause`	pause a task
`remove`	remove a task
`update`	update a task
`create`	create a task

# Examples

List all collector tasks for all agents

$ myrmex collector ls
TASK ID                         AGENT                   NAME                                            SCHEDULE        STATUS  CONFIG                                          PLUGIN
------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------
U5LFBIFR3VAUFJKOSXLLVH57R4      proxy02                 system monitor                                  5m              Running autoconf/prx02/sysmon.yaml                      sys-mon
KZ2JE7KYTVAVNKGXSX5QESEADM      proxy01                 system monitor                                  5m              Running autoconf/prx01/sysmon.yaml                      sys-mon
EIH2YGXJVNGX3AAWMVMDR4FMSY      web05                   system monitor                                  5m              Running autoconf/web05/sysmon.yaml                      sys-mon
NT73KPBCLVH27OXQTVMEYUJ23A      ivr01                   IVR call stats                                  5m              Running asterisk/call-status.yaml                       logmon
OICPWIMJLZCINFBHPAAEJDDDQA      ivr01                   system monitor                                  5m              Running autoconf/ivr01/sysmon.yaml                      sys-mon
FFL4Y3YV2RM4VD4AG23DTVAZAI      db2                     Replication Lag                                 5m              Running oradb/db2/replication_lag.yaml                  sql-collector
LZ2CO27HHBCD3MVN44HHVFJE5Q      db2                     system monitor                                  5m              Running autoconf/db2/sysmon.yaml                        sys-mon
K56DGG6VPZEIPJCB4LKFPUFHRU      ivr02                   system monitor                                  5m              Running autoconf/ivr02/sysmon.yaml                      sys-mon
QGN55C66MNFZ5FBCIXX5H2BTBE      ivr02                   IVR call stats                                  5m              Running asterisk/call-status.yaml                       logmon
...

List all "system monitor" tasks

$ myrmex collector ls --filter "pluginName=sys-mon"
TASK ID                         AGENT                   NAME            SCHEDULE        STATUS  CONFIG                                          PLUGIN
-------------------------------------------------------------------------------------------------------------------------------------------
U5LFBIFR3VAUFJKOSXLLVH57R4      proxy02                 system monitor  5m              Running autoconf/proxy02/sysmon.yaml                 sys-mon
KZ2JE7KYTVAVNKGXSX5QESEADM      proxy01                 system monitor  5m              Running autoconf/proxy01/sysmon.yaml                 sys-mon
EIH2YGXJVNGX3AAWMVMDR4FMSY      web05                   system monitor  5m              Running autoconf/web05/sysmon.yaml                   sys-mon
OICPWIMJLZCINFBHPAAEJDDDQA      ivr01                   system monitor  5m              Running autoconf/ivr01/sysmon.yaml                   sys-mon
LZ2CO27HHBCD3MVN44HHVFJE5Q      db2                     system monitor  5m              Running autoconf/db2/sysmon.yaml                     sys-mon
K56DGG6VPZEIPJCB4LKFPUFHRU      ivr02                   system monitor  5m              Running autoconf/ivr02/sysmon.yaml                   sys-mon
6XTV72QUGJH5TNNCU2XABWSJUI      db1                     system monitor  5m              Running autoconf/db1/sysmon.yaml                     sys-mon
MMI5MRFUVNHN3C622F5M2K2RBQ      api02                   system monitor  5m              Running autoconf/api02/sysmon.yaml                   sys-mon
LYMINBJ4B5CE5CPI7N2WJE6JLM      forms                   system monitor  5m              Running autoconf/forms/sysmon.yaml                   sys-mon
MRVAFL3GK5BU7FUCARREXYUEKU      service01               system monitor  5m              Running autoconf/service01/sysmon.yaml               sys-mon
7GQCLGR23BGVZE7F2DVBMFWSF4      nat01                   system monitor  5m              Running autoconf/nat01/sysmon.yaml                   sys-mon
RTQMGGD7O5DVXHTAYEW6SLOVCA      elk01                   system monitor  5m              Running autoconf/elk01/sysmon.yaml                   sys-mon
SDUTISKHAJCATLQAZYX5MO6TJE      ivr03                   system monitor  5m              Running autoconf/ivr03/sysmon.yaml                   sys-mon
ZWF5QP72IFD5NDDX6EF4QAX6WU      ivr05                   system monitor  5m              Running autoconf/ivr05/sysmon.yaml                   sys-mon
6SGTB6G3DJG4VAFPQ6VLEIP7IM      service02               system monitor  5m              Running autoconf/service02/sysmon.yaml               sys-mon
W476QYNGCNAOZCYO6B67HFAUL4      api01                   system monitor  5m              Running autoconf/api01/sysmon.yaml                   sys-mon
....

List all tasks on specific agent

$myrmex collector ls 72adf789-299c-7e0b-d6a5-bf2ea3a2dce9
TASK ID                         AGENT   NAME                            SCHEDULE        STATUS  CONFIG                                  PLUGIN
------------------------------------------------------------------------------------------------------------------------------------------------
6XTV72QUGJH5TNNCU2XABWSJUI      db1  system monitor                     5m              Running autoconf/db1/sysmon.yaml                sys-mon
7QZBBDPORFNHJK3GMJHCDZSKOU      db1  db1 Instance Status                5m              Running oradb/db1/db-status.yaml                ora-db-status
DK5XDNJU6FM4FKCW4HRIOTPF3A      db1  db1 redo log stats                 5m              Running oradb/db1/redo-stats.yaml               sql-collector
EIZIU6FDH5IIRMVN32AJFPKE5U      db1  db1 archive log stats              10m             Running oradb/db1/arch_logs_stats.yaml          sql-collector
I3EZTFYTSVAA3DJYHDWRRAZGZU      db1  db1 alert log                      5m              Running oradb/db1/logmon-alertlog.yaml          logmon
JAK42E6DYBENVEVZP3F2EJUE2I      db1  sql stats (db1)                    30m             Running oradb/db1/sqlstats.yaml                 ora-sqlstats
LOAXWCNVIZMHTCCLCSCJNVMJIM      db1  listener Listener Status           5m              Running oralsnr/db1/LISTENER.yaml               ora-listener-status
RFHAP6PAVRI65EQMOYRFLGBSAM      db1  db1 Datapatch Info                 24h             Running oradb/db1/sql-patch.yaml                ora-sql-patches
SGX5C24KWFCKHOV2B2BRQIUJIQ      db1  service provider api status        10m             Running custom/service_provider_api_stats.yaml  sql-collector
URC5CTAYSRLXNKPZONZZRMYA64      db1  db1 Tablespace Status              15m             Running oradb/db1/ts-status.yaml                ora-ts-status

List paused tasks

$ myrmex collector ls --filter "status=Paused"
TASK ID                         AGENT   NAME                                    SCHEDULE        STATUS  CONFIG                                  PLUGIN
--------------------------------------------------------------------------------------------------------------------------------------------------
RSS53VYUZNFURGJ773T6UJABCQ      db3    oracle database size stats (dwdev)2     2m              Paused  oradb/db3/size-stats.yaml               sql-collector
RYMIJAJUCZONDO6STB5DMU4SJA      obi    OBI Log Monitoring - DEV obis1          5m              Paused  wls/obi/dev/bi/logmon-obis1-diag.yaml   logmon

Create a collector

myrmex collector create --agent 94145cd8-527d-465b-d7b4-f9d9312ddb17 --name "Docker Stats" --plugin docker-stats --config docker-stats.yaml --sched 2m

Start a collector

myrmex collector start RSS53VYUZNFURGJ773T6UJABCQ

Pause a collector

myrmex collector pause RSS53VYUZNFURGJ773T6UJABCQ

Remove a collector

myrmex collector remove RSS53VYUZNFURGJ773T6UJABCQ

Change collector name and schedule

myrmex collector update --name "system monitor - (CPU/VM/IO)" --schedule "1m" 6XTV72QUGJH5TNNCU2XABWSJUI

Rename all "system monitor" collector to "system monitor - (CPU/VM/IO)" and set schedule to "1m"

$ for uuid in $(myrmex collector ls --filter "name=system monitor" --filter "pluginName=sys-mon" --format "{{.UUID}}")
> do
> myrmex collector update --name "system monitor - (CPU/VM/IO)" --schedule "1m" $uuid
> done

# myrmex action

Manages action tasks

Command	Description
`ls`	list actions tasks
`cat`	shows the configuration file for a task
`cat-config-file`	shows a action task configuration file by path
`start`	start a task
`pause`	pause a task
`remove`	remove a task
`create`	create a task

# Examples

Create an action task

myrmex action create --agent 5c186920-2ab3-79ae-a297-6aad30110114 --plugin ora-ts-alloc --config autoconf/kilo/alloc_tablespace.yaml

# myrmex autoconf

Autoconfigure collectors and actions

Command	Description
`generate`	generates configurations
`sync`	syncs auto configuratrions
`state`	reports auto configuration state

For more information and usage see Monitoring Automation

# myrmex maintenance

Executes maintenance actions

Command	Description
`unindex-source`	deletes a metric source from the index. it will reappear if seen again in a metric or event
`backup`	backup the monitoring server configuration

# myrmex admin

Manages access control to polaris

Command	Description
`users`	list users
`roles`	list available roles
`useradd`	add a user
`userdel`	delete a user
`passwd`	change a user password
`roleadd`	add roles to a user
`roledel`	remvoe a role from a user
`userroles`	list roles assigned to a user
`userunlock`	unlock a user
`service-acc`	manage service accounts

# mymrex admin service-acc

Manage service accounts

Command	Description
`list`	list service accounts
`add`	add or update a service account
`import`	import a service account from a json file
`del`	delete a service account
`show`	show details for a service account

# myrmex security

Manages security

Command	Description
`tokens`	list join tokens for agents
`rotate-tokens`	rotate join tokens
`quarantine`	reports information about quarantined git files

# myrmex security quarantine

Command	Description
`ls`	list quarantined file

# myrmex auxdata

Work with auxilary data in the timeseries database

Command	Description
`import`	imports an auxiliary data file in json format

← Ansible Automation Monitoring Automation →

# Usage

# Command Autocompletion

# Connect to a myrmex server

# Remote connection over SSH

# Output filtering and formatting

# myrmex agent

# Examples

# myrmex collector

# Examples

# myrmex action

# Examples

# myrmex autoconf

# myrmex maintenance

# myrmex admin

# mymrex admin service-acc

# myrmex security

# myrmex security quarantine

# myrmex auxdata

# Connect to a `myrmex` server