NXLog Agent Minder Public APIs

Counting agents

Table 1. agents/count
method + URI description

GET BASE_URI/agents/count?filter=<filter expression>

return number of agents matching the specified filter or all agents should no filter be given

request

curl -k -sS -G 'https://minder-server:8080/agents/count' --data-urlencode 'filter=os = Linux'

response

5


Listing agents

Table 2. agents/ids
method + URI description

GET BASE_URI/agents/ids?filter=<filter expression>

return IDs of agents matching the specified filter or all agents should not filter be given

request

curl -k -sS -G 'https://minder-server:8080/agents/ids'

response

[
  "950c5ad0-3bc3-11ec-b62a-9b0aa35e27a6",
  "3371cf42-3be8-11ec-9fb0-2bd90580b515",
  "2f7cc4a0-3be8-11ec-819a-034907e0b7b5",
  "995a281a-3bc3-11ec-aa95-63fd7974b705",
  "373c4436-3be8-11ec-9ac8-df8cc28a8d2d"
]


Agent information

Table 3. agents
method + URI description

GET BASE_URI/agents?filter=<filter expression>

return information about agents matching the specified filter or all agents should not filter be given

request

curl -k -sS -G 'https://minder-server:8080/agents' --data-urlencode 'filter=name = agent-1'

response

[
  {
    "status": "success",
    "uid": "3561fbfd-c575-11ec-8001-58411d677fde",
    "hostname": "agent-1",
    "data": {
      "online": true,
      "persist": true,
      "enrolled": false,
      "hostname": "agent-1",
      "os": "Linux",
      "version": "5.4.7313",
      "start_time": "2022-04-28T08:15:26.737077Z",
      "labels": {
        "dplstate": "enrolled"
      },
      "modules": {
        "in": {
          "type": "im_null",
          "kind": "input",
          "status": "running",
          "variables": []
        },
        "out": {
          "type": "om_null",
          "kind": "output",
          "status": "running",
          "variables": []
        },
        "json": {
          "type": "xm_json",
          "kind": "extension"
        }
      },
      "routes": {
        "name": "default_route",
        "in_use": true,
        "default_route": {
          "modules": [
            "in",
            "out"
          ]
        }
      },
      "config_id": "bb353771-1d57-11ed-8000-1fdfdd2bedbf",
      "add_time": "2022-04-28T08:09:32.070442763Z",
      "persist_time": "2022-04-28T08:09:32.070442763Z",
      "connect_time": "2022-04-28T08:15:26.750677623Z",
      "poll_time": "2022-04-28T08:15:26.750137784Z",
      "cluster_node_id": "fdce94b7-c6ca-11ec-8000-ffd3b784b336",
      "address": "127.0.0.1:48232",
      "node_address": "127.0.0.1:4041",
      "pid": 194088,
      "certificate": {
        "not_before": "2022-04-26T15:30:05Z",
        "not_after": "2024-03-28T18:07:47Z",
        "subject": "CN=agent-1",
        "digest_sha256": "46a517d4baea4b304f4ae6911e3d0c9b1d11feb9f0c5887dbbb70963a726d36e"
      },
      "comment": "some manually added comment"
    }
  }
]


GET BASE_URI/agents/:950c5ad0-3bc3-11ec-b62a-9b0aa35e27a6

return information about agent with id 950c5ad0-3bc3-11ec-b62a-9b0aa35e27a6

request

curl -k -sS -G 'https://minder-server:8080/agents/:950c5ad0-3bc3-11ec-b62a-9b0aa35e27a6'

response

{
  "online": true,
  "persist": true,
  "enrolled": false,
  "hostname": "agent-1",
  "os": "Linux",
  "version": "5.4.7313",
  "start_time": "2022-04-28T08:15:26.737077Z",
  "labels": {
    "dplstate": "enrolled"
  },
  "modules": {
    "in": {
      "type": "im_null",
      "kind": "input",
      "status": "running",
      "variables": []
    },
    "out": {
      "type": "om_null",
      "kind": "output",
      "status": "running",
      "variables": []
    },
    "json": {
      "type": "xm_json",
      "kind": "extension"
    }
  },
  "routes": {
    "default_route": {
      "name": "default_route",
      "in_use": true,
      "modules": [
        "in",
        "out"
      ]
    }
  },
  "add_time": "2022-04-28T08:09:32.070442763Z",
  "persist_time": "2022-04-28T08:09:32.070442763Z",
  "connect_time": "2022-04-28T08:15:26.750677623Z",
  "poll_time": "2022-04-28T08:15:26.750137784Z",
  "cluster_node_id": "fdce94b7-c6ca-11ec-8000-ffd3b784b336",
  "address": "127.0.0.1:48232",
  "node_address": "127.0.0.1:4041",
  "pid": 194088,
  "certificate": {
    "not_before": "2022-04-26T15:30:05Z",
    "not_after": "2024-03-28T18:07:47Z",
    "subject": "CN=agent-1",
    "digest_sha256": "46a517d4baea4b304f4ae6911e3d0c9b1d11feb9f0c5887dbbb70963a726d36e"
  },
  "comment": "some manually added comment"
}


Agent statistics

Table 4. agents/stats
method + URI description

GET BASE_URI/agents/stats?filter=<filter expression>

return statistics of the agents matching the specified filter or all agents should not filter be given

request

curl -k -sS -G 'https://minder-server:8080/agents/stats' --data-urlencode 'filter=name = agent-1'

response

[
  {
    "status": "success",
    "uid": "3561fbfd-c575-11ec-8001-58411d677fde",
    "hostname": "agent-1",
    "data": {
      "poll_time": "2022-04-28T08:15:26.750137784Z",
      "memory_used": 12742656,
      "cpu_load": 0.05999999865889549,
      "modules": {
        "input": {
          "events_received": 0,
          "events_dropped": 0,
          "events_forwarded": 10,
          "queue_limit": 100,
          "queue_size": 0,
          "batch_size": 50
        },
        "output": {
          "events_received": 10,
          "events_dropped": 0,
          "events_forwarded": 0,
          "queue_limit": 100,
          "queue_size": 0,
          "batch_size": 50
        }
      },
      "routes": {
        "route": {
          "events_received": 10,
          "events_dropped": 0,
          "events_forwarded": 10
        }
      }
    }
  }
]


GET BASE_URI/agents/:950c5ad0-3bc3-11ec-b62a-9b0aa35e27a6/stats

return statistics of the agent with id 950c5ad0-3bc3-11ec-b62a-9b0aa35e27a6

request

curl -k -sS -G 'https://minder-server:8080/agents/:950c5ad0-3bc3-11ec-b62a-9b0aa35e27a6/stats'

response

{
  "poll_time": "2022-04-28T08:15:26.750137784Z",
  "memory_used": 12742656,
  "cpu_load": 0.05999999865889549,
  "modules": {
    "input": {
      "events_received": 0,
      "events_dropped": 0,
      "events_forwarded": 10,
      "queue_limit": 100,
      "queue_size": 0,
      "batch_size": 50
    },
    "output": {
      "events_received": 10,
      "events_dropped": 0,
      "events_forwarded": 0,
      "queue_limit": 100,
      "queue_size": 0,
      "batch_size": 50
    }
  },
  "routes": {
    "route": {
      "events_received": 10,
      "events_dropped": 0,
      "events_forwarded": 10
    }
  }
}


Agent commands

Table 5. agents
method + URI description

POST BASE_URI/agents?filter=<filter expression>

execute an agent operation (start/restart/stop/persist_id) or a configuration operation (set_config/update_config) on agents matching the specified filter or all agents should no filter be given. POST data must contain the command in json format: {"operation":"command"}. Configuration-related commands must contain the config_id field.

request

curl -k -sS -H "content-type: application/json" -X POST 'https://minder-server:8080/agents?filter=name+%3D+agent-1' -d '{"operation":"restart"}'

response

[
  {
    "status": "success",
    "uid": "950c5ad0-3bc3-11ec-b62a-9b0aa35e27a6",
    "hostname": "agent-1"
  }
]

request

curl -k -sS -H "content-type: application/json" -X POST 'https://minder-server:8080/agents?filter=name+%3D+agent-1' -d '{"operation":"set_config","config_id":"aaf792f2-197a-11ed-861d-0242ac120002"}'

response

  • The API responds with HTTP/1.1 204 No Content on success

  • The API responds with HTTP/1.1 500 Internal Server Error if the configuration is not found or invalid

POST BASE_URI/agents/:950c5ad0-3bc3-11ec-b62a-9b0aa35e27a6

execute an operation (start/restart/stop/persist_id) or a configuration operation (set_config/update_config) on 950c5ad0-3bc3-11ec-b62a-9b0aa35e27a6. POST request body must contain the command in json format: { "operation": "command" }.

request

curl -k -sS -H "content-type: application/json"  -X POST 'https://minder-server:8080/agents/:950c5ad0-3bc3-11ec-b62a-9b0aa35e27a6' -d '{"operation":"restart"}'

response

  • The API responds with HTTP/1.1 204 No Content on success

  • The API responds with HTTP/1.1 404 Not Found if the agent is unknown to NXLog Agent Minder

request

curl -k -sS -H "content-type: application/json"  -X POST 'https://minder-server:8080/agents/:950c5ad0-3bc3-11ec-b62a-9b0aa35e27a6' -d '{ "operation": "update_config" }'

response

  • The API responds with HTTP/1.1 204 No Content on success

  • The API responds with HTTP/1.1 500 Internal Server Error if the configuration is not found

Module information

Table 6. agents/modules
method + URI description

GET BASE_URI/agents/modules/:module1?filter=<filter expression>

return info about module module1 of agents matching the specified filter or all agents should no filter be given.

request

curl -k -sS -G 'https://minder-server:8080/agents/modules/:module1' --data-urlencode 'filter=name = agent-1'

response

[
  {
    "status": "success",
    "uid": "3561fbfd-c575-11ec-8001-58411d677fde",
    "hostname": "agent-1",
    "data": {
      "type": "im_null",
      "kind": "input",
      "status": "running",
      "variables": []
    }
  }
]


GET BASE_URI/agents/:950c5ad0-3bc3-11ec-b62a-9b0aa35e27a6/modules/:module1

return info about module module1 of 950c5ad0-3bc3-11ec-b62a-9b0aa35e27a6

request

curl -k -sS -G 'https://minder-server:8080/agents/:950c5ad0-3bc3-11ec-b62a-9b0aa35e27a6/modules/:module1'

response

{
  "type": "im_null",
  "kind": "input",
  "status": "running",
  "variables": []
}


Module statistics

Table 7. agents/modules/stats
method + URI description

GET BASE_URI/agents/modules/:module1/stats?filter=<filter expression>

return statistics of the module1 module of agents matching the specified filter or all agents should no filter be given.

request

curl -k -sS -G 'https://minder-server:8080/agents/modules/:module1/stats' --data-urlencode 'filter=name = agent-1'

response

[
  {
    "status": "success",
    "uid": "3561fbfd-c575-11ec-8001-58411d677fde",
    "hostname": "agent-1",
    "data": {
      "events_received": 10,
      "events_dropped": 0,
      "events_forwarded": 10,
      "queue_limit": 100,
      "queue_size": 0,
      "batch_size": 50
    }
  }
]


GET BASE_URI/agents/:950c5ad0-3bc3-11ec-b62a-9b0aa35e27a6/modules/:module1/stats

return statistics of the module1 module of 950c5ad0-3bc3-11ec-b62a-9b0aa35e27a6

request

curl -k -sS -G 'https://minder-server:8080/agents/:950c5ad0-3bc3-11ec-b62a-9b0aa35e27a6/modules/:module1/stats'

response

{
  "events_received": 10,
  "events_dropped": 0,
  "events_forwarded": 10,
  "queue_limit": 100,
  "queue_size": 0,
  "batch_size": 50
}


Module commands

Table 8. agents/modules
method + URI description

POST BASE_URI/agents/modules/:module1?filter=<filter expression>

execute an operation (start/restart/stop) for the module module1 on agents matching the specified filter or all agents should no filter be given. POST data must contain the command in json format: {"operation": "command" }

request

curl -k -sS -H "content-type: application/json" -X POST \
    'https://minder-server:8080/agents/modules/:module1?filter=name+%3D+agent-1' \
    -d '{"operation":"restart"}'

response

[
  {
    "status": "success",
    "uid": "950c5ad0-3bc3-11ec-b62a-9b0aa35e27a6",
    "hostname": "agent-1"
  }
]


Deleting agents

Table 9. agents/delete
method + URI description

DELETE BASE_URI/agents?filter=<filter expression>

delete from the permanent data storage and forget when disconnecting the agents matching the specified filter or all agents should no filter be given

request

curl -k -sS -H "content-type: application/json" -X DELETE 'https://minder-server:8080/agents?filter=name+%3D+agent-1'

response

[
  {
    "status": "success",
    "uid": "950c5ad0-3bc3-11ec-b62a-9b0aa35e27a6",
    "hostname": "agent-1"
  }
]


DELETE BASE_URI/agents/:950c5ad0-3bc3-11ec-b62a-9b0aa35e27a6

delete the agent from 950c5ad0-3bc3-11ec-b62a-9b0aa35e27a6 the permanent data storage and forget when disconnecting

request

curl -k -sS -H "content-type: application/json"  -X DELETE 'https://minder-server:8080/agents/:950c5ad0-3bc3-11ec-b62a-9b0aa35e27a6'

response

  • The API responds with HTTP/1.1 204 No Content on success

  • The API responds with HTTP/1.1 404 Not Found if the agent is unknown to NXLog Agent Minder

Reading files

Table 10. agents/files
method + URI description

GET BASE_URI/agents/files/:path/:file?filter=<filter expression>

retrieve the content of the file file under ACL path of agents matching the specified filter or all agents should no filter be given in the response body. The response is a JSON structure as multiple agents may contain files named the same.

request

curl -k -sS -G 'https://minder-server:8080/agents/files/:conf/:managed.conf' --data-urlencode 'filter=name = agent-2'

response

[
  {
    "status": "success",
    "uid": "995a281a-3bc3-11ec-aa95-63fd7974b705",
    "hostname": "agent-2",
    "data": "LogLevel    INFO\nLogFile     %MYLOGFILE%\n\n<Extension admin>\n    Module      xm_admin\n\n    Host        192.168.1.1:4041\n    SocketType  SSL\n    CAFile      %CERTDIR%/agent-ca.pem\n    CertFile    %CERTDIR%/agent-cert.pem\n    CertKeyFile %CERTDIR%/agent-key.pem\n\n    <ACL conf>\n        Directory   %CONFDIR%\n        AllowRead   TRUE\n        AllowWrite  TRUE\n    </ACL>\n\n    <ACL cert>\n        Directory   %CERTDIR%\n        AllowRead   TRUE\n        AllowWrite  TRUE\n    </ACL>\n\n    <labels>\n        dplstate    \"enrolled\"\n    </labels>\n</Extension>\n"
  }
]


GET BASE_URI/agents/:950c5ad0-3bc3-11ec-b62a-9b0aa35e27a6/files/:path/:file

retrieve the content of the file file under ACL path of 950c5ad0-3bc3-11ec-b62a-9b0aa35e27a6 in the response body. The content is returned as plain text.

request

curl -k -sS -G 'https://minder-server:8080/agents/:950c5ad0-3bc3-11ec-b62a-9b0aa35e27a6/files/:conf/:managed.conf'

response

LogLevel    INFO
LogFile     %MYLOGFILE%

<Extension admin>
    Module      xm_admin

    Host        192.168.1.1:4041
    SocketType  SSL
    CAFile      %CERTDIR%/agent-ca.pem
    CertFile    %CERTDIR%/agent-cert.pem
    CertKeyFile %CERTDIR%/agent-key.pem

    <ACL conf>
        Directory   %CONFDIR%
        AllowRead   TRUE
        AllowWrite  TRUE
    </ACL>

    <ACL cert>
        Directory   %CERTDIR%
        AllowRead   TRUE
        AllowWrite  TRUE
    </ACL>

    <labels>
        dplstate    "enrolled"
    </labels>
</Extension>


Writing files

Table 11. agents/files
method + URI description

PUT BASE_URI/agents/files/:path/:file?filter=<filter expression>

put the content of the request body into the file file under ACL path of agents matching the specified filter or all agents should no filter be given

request

curl -k -sS -X PUT 'https://minder-server:8080/agents/files/:conf/:local_labels?filter=name+%3D+agent-1' -d 'phone "+155555555"'

response

[
  {
    "status": "success",
    "uid": "950c5ad0-3bc3-11ec-b62a-9b0aa35e27a6",
    "hostname": "agent-1"
  }
]


PUT BASE_URI/agents/:950c5ad0-3bc3-11ec-b62a-9b0aa35e27a6/files/:path/:file

put the content of the request body into the file file under ACL path of 950c5ad0-3bc3-11ec-b62a-9b0aa35e27a6

request

curl -k -sS -X PUT 'https://minder-server:8080/agents/:950c5ad0-3bc3-11ec-b62a-9b0aa35e27a6/files/:conf/:local_labels' -d 'phone "+155555552"'

response

  • The API responds with HTTP/1.1 204 No Content on success

  • The API responds with HTTP/1.1 404 Not Found if the file cannot be found on the agent

Reading the internal log

Table 12. agents/log
method + URI description

GET BASE_URI/agents/log?filter=<filter expression>&maxSize=<maximum size in bytes>

retrieve the content of the log file of the agents matching the specified filter or all agents should no filter be given limited by maxSize bytes (or 10000 bytes if not specified)

request

curl -k -sS -G 'https://minder-server:8080/agents/log?maxSize=100' --data-urlencode 'filter=name = agent-1'

response

[
  {
    "status": "success",
    "uid": "950c5ad0-3bc3-11ec-b62a-9b0aa35e27a6",
    "hostname": "agent-1",
    "data": "3:04:42 INFO [xm_admin

admin] getLog called\n2020-12-09 13:05:03 INFO [xm_admin

admin] getLog called\n" } ] ----

GET BASE_URI/agents/:950c5ad0-3bc3-11ec-b62a-9b0aa35e27a6/log?maxSize=1024

retrieve the content of the log file of 950c5ad0-3bc3-11ec-b62a-9b0aa35e27a6 limited by maxSize bytes (or 10000 bytes if not specified)

Reading the configuration

Table 13. agents/config
method + URI description

GET BASE_URI/agents/config?filter=<filter expression>

retrieve the content of the config file of agents matching the specified filter or all agents should no filter be given

request

curl -k -sS -G 'https://minder-server:8080/agents/config' --data-urlencode 'filter=name = agent-1'

response

[
  {
    "status": "success",
    "uid": "950c5ad0-3bc3-11ec-b62a-9b0aa35e27a6",
    "hostname": "agent-1",
    "data": "LogLevel    INFO\nLogFile     %MYLOGFILE%\n\n<Extension admin>\n    Module      xm_admin\n\n    Host        192.168.1.1:4041\n    SocketType  SSL\n    CAFile      %CERTDIR%/agent-ca.pem\n    CertFile    %CERTDIR%/agent-cert.pem\n    CertKeyFile %CERTDIR%/agent-key.pem\n\n    <ACL conf>\n        Directory   %CONFDIR%\n        AllowRead   TRUE\n        AllowWrite  TRUE\n    </ACL>\n\n    <ACL cert>\n        Directory   %CERTDIR%\n        AllowRead   TRUE\n        AllowWrite  TRUE\n    </ACL>\n\n    <labels>\n        dplstate    \"configured\"\n        include_stdout /usr/local/bin/get_docker_id.sh\n        include_stdout /usr/local/bin/custom_labels.sh\n        template    \"tpl1\"\n    </labels>\n</Extension>\n\n<Input i_n>\n   Module im_null\n</Input>\n\n<Output module1>\n   Module om_null\n</Output>\n\n<Route r_n>\n   Path i_n => module1\n</Route>"
  }
]


GET BASE_URI/agents/:950c5ad0-3bc3-11ec-b62a-9b0aa35e27a6/config

retrieve the content of the config file of 950c5ad0-3bc3-11ec-b62a-9b0aa35e27a6

request

curl -k -sS -G 'https://minder-server:8080/agents/:950c5ad0-3bc3-11ec-b62a-9b0aa35e27a6/config'

response

LogLevel  INFO
LogFile   %MYLOGFILE%

<Extension admin>
    Module      xm_admin

    Host        192.168.1.1:4041
    SocketType  SSL
    CAFile      %CERTDIR%/agent-ca.pem
    CertFile    %CERTDIR%/agent-cert.pem
    CertKeyFile %CERTDIR%/agent-key.pem

    <ACL conf>
        Directory   %CONFDIR%
        AllowRead   TRUE
        AllowWrite  TRUE
    </ACL>

    <ACL cert>
        Directory   %CERTDIR%
        AllowRead   TRUE
        AllowWrite  TRUE
    </ACL>

    <labels>
        dplstate    "configured"
        include_stdout /usr/local/bin/get_docker_id.sh
        include_stdout /usr/local/bin/custom_labels.sh
        template    "tpl1"
    </labels>
</Extension>

<Input i_n>
   Module im_null
</Input>

<Output module1>
   Module om_null
</Output>

<Route r_n>
   Path i_n => module1
</Route>


Writing the configuration

Table 14. agents/config
method + URI description

PUT BASE_URI/agents/config?filter=<filter expression>

put the content of the config file of agents matching the specified filter or all agents should no filter be given

request

curl -k -sS -X PUT 'https://minder-server:8080/agents/config?filter=name+%3D+agent-1'

response

[
  {
    "status": "success",
    "uid": "950c5ad0-3bc3-11ec-b62a-9b0aa35e27a6",
    "hostname": "agent-1"
  }
]
This call performs no checks on the validity of the configuration file. Invalid configuration may make the agent unreachable after restart.

PUT BASE_URI/agents/:950c5ad0-3bc3-11ec-b62a-9b0aa35e27a6/config

put the content of the config file of 950c5ad0-3bc3-11ec-b62a-9b0aa35e27a6

request

curl -k -sS -X PUT 'https://minder-server:8080/agents/:950c5ad0-3bc3-11ec-b62a-9b0aa35e27a6/config' -d "Better be a valid configuration file!"

response

  • The API responds with HTTP/1.1 204 No Content on success

This call performs no checks on the validity of the configuration file. Invalid configuration may make the agent unreachable after restart.

Reading agent state

Table 15. agents/state
method + URI description

GET BASE_URI/agents/state?filter=<filter expression>

get the state (ok, warning or error) of agents matching the specified filter or all agents should no filter be given

request

curl -k -sS -G 'https://minder-server:8080/agents/state' --data-urlencode 'filter=state not ok'

response

[
  {
    "status": "success",
    "uid": "3561fbfd-c575-11ec-8001-58411d677fde",
    "hostname": "agent-1",
    "data": {
      "status": "error",
      "errors": [
        "module f has failed to start"
      ],
      "warnings": [
        "agent has no certificate"
      ]
    }
  }
]


GET BASE_URI/agents/:950c5ad0-3bc3-11ec-b62a-9b0aa35e27a6/state

get the state (ok, warning or error) of 950c5ad0-3bc3-11ec-b62a-9b0aa35e27a6

request

curl -k -sS -G 'https://minder-server:8080/agents/:950c5ad0-3bc3-11ec-b62a-9b0aa35e27a6/state'

response

{
  "status": "error",
  "errors": [
    "module f has failed to start"
  ],
  "warnings": [
    "agent has no certificate"
  ]
}


Adding a new configuration template

When adding a new template, the comment field is optional.

Table 16. templates/adding
method + URI description

POST BASE_URI/templates

add a new template

request

curl -k -sS -H "content-type: application/json" -X POST \
    'https://localhost:8080/templates' \
    -d '{ "name": "template1", "contents": "<Input null>\nModule im_null\n</Input>\n", "comment": "a new comment" }'

response

* This endpoint responds with the Uuid of the template added, or an error why that could not be done.
1833a995-f5eb-11ec-8000-b41973229aaa

Listing configuration template identifiers

Table 17. templates/ids
method + URI description

GET BASE_URI/templates/ids

get a list of the uuids of templates NXLog Agent Minder currently stores

request

curl -k -sS -G 'https://minder-server:8080/templates/ids'

response

[
    "0ba36315-f3af-11ec-8000-7ca797aa98a1",
    "a35e6f4e-f5e8-11ec-8000-42a37bb809fe",
    "a38d8ff2-f5e8-11ec-8001-3fe36570a88d"
]


Listing configuration template identifiers with names

Table 18. templates/ids_names
method + URI description

GET BASE_URI/templates/names

get a list of template uuids and corresponding names

request

curl -k -sS -G 'https://minder-server:8080/templates/names'

response

{
    "90de9ef3-1d48-11ed-8000-7a3d5b3e782d": "name 1",
    "9dc39781-1d48-11ed-8001-2df02aeeac40": "name 1",
    "2167572a-f5eb-11ec-8002-d3ebd461e234": "names aren't required to be unique"
}


Retrieving a configuration template

Table 19. templates/retrieving
method + URI description

GET BASE_URI/templates/:template_id

retrieve the content of the template based on it’s Uuid

request

curl -k -sS -G 'https://minder-server:8080/templates/:1833a995-f5eb-11ec-8000-b41973229aaa'

response

{
    "name": "the name of your template",
    "contents": "<Extension agent_managment>\n    Module          xm_admin\n    Host            0.0.0.0:4041\n    SocketType      SSL\n    CAFile          %CERTDIR%/agent-ca.pem\n    CertFile        %CERTDIR%/agent-cert.pem\n    CertKeyFile     %CERTDIR%/agent-key.pem\n    <ACL conf>\n        Directory   %CONFDIR%\n        AllowRead   TRUE\n        AllowWrite  TRUE\n    </ACL>\n    <ACL cert>\n        Directory   %CERTDIR%\n        AllowRead   TRUE\n        AllowWrite  TRUE\n    </ACL>\n</Extension>\n",
    "add_time": "2022-08-30T06:38:31.568151531Z",
    "update_time": "2022-08-30T08:39:41.421149872Z",
    "comment": "arbitrary comment"
}


Updating a configuration template

For template updates, all three fields (name, contents and comment) are optional, and only the fields present get updated. For template contents, the same parsing and validation steps are executed. In order to delete a comment, you can use the null JSON value for the comment field.

Table 20. templates/updating
method + URI description

PUT BASE_URI/templates/:template_id

update a template

request

curl -k -sS -H "content-type: application/json" -X PUT 'https://localhost:8080/templates/:1833a995-f5eb-11ec-8000-b41973229aaa' -d '{ "name": "updated name", "contents": "<Route>\n    im_null => om_null\n</Route>\n" }'

curl -k -sS -H "content-type: application/json" -X PUT 'https://localhost:8080/templates/:1833a995-f5eb-11ec-8000-b41973229aaa' -d '{ "contents": "<Route>\n    im_null => om_null\n</Route>\n" }'

curl -k -sS -H "content-type: application/json" -X PUT 'https://localhost:8080/templates/:1833a995-f5eb-11ec-8000-b41973229aaa' -d '{ "name": "updated name" }'
curl -k -sS -H "content-type: application/json" -X PUT 'https://localhost:8080/templates/:1833a995-f5eb-11ec-8000-b41973229aaa' -d '{ "comment": "updated comment" }'
curl -k -sS -H "content-type: application/json" -X PUT 'https://localhost:8080/templates/:1833a995-f5eb-11ec-8000-b41973229aaa' -d '{ "comment": null }'

Removing a configuration template

Table 21. templates/deleting
method + URI description

DELETE BASE_URI/templates/:template_id

remove a template

request

curl -k -sS -X DELETE 'https://localhost:8080/templates/:1833a995-f5eb-11ec-8000-b41973229aaa'

Adding a configuration

Configurations are named sets of template parts identified by an Uuid.

Table 22. configurations/adding
method + URI description

POST BASE_URI/configs/

add a configuration

request

curl -k -sS -H "content-type: application/json" -X PUT 'https://localhost:8080/configs/'
-d '{
    "name": "bela",
    "parts": [
        "da81a80f-f768-11ec-8000-a6382b1fc35f",
        "db7459b8-f611-11ec-8000-8fbd5b0db1c4",
        "dbd4b301-f611-11ec-8001-0a1d6b4a1c64",
        "dc2e754a-f611-11ec-8002-ad5831ecd994"
    ],
    "comment": "some comment"
}'

response

1833a995-f5eb-11ec-8000-b41973229aaa

Listing existing configuration identifiers

Table 23. configurations/listing
method + URI description

`GET BASE_URI/configs/ids

List the identifiers of configurations. The optional template_id parameter lists only the configurations that contain the given template.

request

curl -k -sS -G 'https://minder-server:8080/configs/ids?template_id=1298abba-f6c7-11ec-8000-15aff8d94451'

response

[
    "1298abba-f6c7-11ec-8000-15aff8d94456",
    "a33faa22-f76c-11ec-8000-6c5382b5501e",
    "a37718e6-f76c-11ec-8001-fac643f9b51b"
]

Listing existing configuration identifiers with names

Table 24. configurations/listing_ids_and_names
method + URI description

`GET BASE_URI/configs/names

list the identifiers and names of configurations. The optional template_id parameter lists only the configurations that contain the given template.

request

curl -k -sS -G 'https://minder-server:8080/configs/names?template_id=1298abba-f6c7-11ec-8000-15aff8d94451'

response

{
    "1298abba-f6c7-11ec-8000-15aff8d94456": "Name 1",
    "a33faa22-f76c-11ec-8000-6c5382b5501e": "ਨਾਮ 2",
    "a37718e6-f76c-11ec-8001-fac643f9b51b": "Name 3"
}

Retrieving a configuration

Table 25. configurations/get
method + URI description

`GET BASE_URI/configs/:config_id

return the configuration referenced by the given config_id

request

curl -k -sS -G 'https://minder-server:8080/configs/:1833a995-f5eb-11ec-8000-b41973229aaa'

response

{
    "name": "Name 1",
    "parts": [
        "da81a80f-f768-11ec-8000-a6382b1fc35f",
        "db7459b8-f611-11ec-8000-8fbd5b0db1c4",
        "dbd4b301-f611-11ec-8001-0a1d6b4a1c64",
        "dc2e754a-f611-11ec-8002-ad5831ecd994"
    ],
    "comment": "the comment you added"
}

Retrieving a configuration’s contents

Table 26. configurations/get_contents
method + URI description

`GET BASE_URI/configs/:config_id/contents

return the contents of the configuration referenced by the given config_id

request

curl -k -sS -G 'https://minder-server:8080/configs/:1833a995-f5eb-11ec-8000-b41973229aaa'/contents

response

<Extension agent_managment>
    Module          xm_admin
    Host            0.0.0.0
    Port            4041
    SocketType      SSL
    CAFile          %CERTDIR%/agent-ca.pem
    CertFile        %CERTDIR%/agent-cert.pem
    CertKeyFile     %CERTDIR%/agent-key.pem
    <ACL conf>
        Directory   %CONFDIR%
        AllowRead   TRUE
        AllowWrite  TRUE
    </ACL>
    <ACL cert>
        Directory   %CERTDIR%
        AllowRead   TRUE
        AllowWrite  TRUE
    </ACL>
</Extension>

Updating a configuration

For the update operation, all three fields (name, parts, and comment) are optional, and can be used together in any combination. Only the fields specified get updated. In order to delete a comment, you can use a null JSON value.

Table 27. configurations/updating
method + URI description

PUT BASE_URI/configs/:config_id

update an existing configuration

request

curl -k -sS -H "content-type: application/json" -X PUT 'https://localhost:8080/configs/:1833a995-f5eb-11ec-8000-b41973229aaa'
    -d '{ "name": "name updated", "parts": ["da81a80f-f768-11ec-8000-a6382b1fc35f"] }'

curl -k -sS -H "content-type: application/json" -X PUT 'https://localhost:8080/configs/:1833a995-f5eb-11ec-8000-b41973229aaa'
    -d '{ "name": "name updated" }'

curl -k -sS -H "content-type: application/json" -X PUT 'https://localhost:8080/configs/:1833a995-f5eb-11ec-8000-b41973229aaa'
    -d '{ "parts": ["da81a80f-f768-11ec-8000-a6382b1fc35f"] }'

curl -k -sS -H "content-type: application/json" -X PUT 'https://localhost:8080/configs/:1833a995-f5eb-11ec-8000-b41973229aaa'
    -d '{ "comment": "updated comment" }'

curl -k -sS -H "content-type: application/json" -X PUT 'https://localhost:8080/configs/:1833a995-f5eb-11ec-8000-b41973229aaa'
    -d '{ "comment": null }'

Remove a configuration

Table 28. configurations/deleting
method + URI description

DELETE BASE_URI/configs/:config_id

remove an existing configuration

request

curl -k -sS -X DELETE 'https://localhost:8080/configs/:1833a995-f5eb-11ec-8000-b41973229aaa'

Enrolling agents

Enrolling agents is a complex procedure. It consists of the following steps:

  • generating connection configuration

  • generating client key

  • generating client certificate

  • pushing the connection configuration to the targeted agents set

  • pushing the client key to the targeted agent set

  • pushing the client certificate to the targeted agent set

  • pushing the CA certificate to the targeted agent set

  • restarting the targeted agent set

All of these steps are handled in the background by NXLog Agent Minder.

To enroll your agents you will need to provide enough information to generate a valid configuration. There are two ways to do this: you can either provide the connection mode and the apparent socket address (192.168.1.1:4041 in our examples) of your Minder instance, or use a pre-defined configuration.

If your agents already have a valid configuration this will overwrite that, effectively resetting the agent to a blank state.
Table 29. agents/enroll

method + URI

description

POST BASE_URI/agents/enroll?filter=<filter expression>

enroll agents matching the specified filter or all agents should no filter be given (see description of enrollment request format below)

request

curl -k -sS -H "content-type: application/json" \
	-X POST 'https://minder-server:8080/agents/enroll?filter=name+%3D+agent-2' \
	-d '{"connection":{"mode":"connect","address":"192.168.1.1:4041"}}'

response

[
  {
    "status": "success",
    "uid": "995a281a-3bc3-11ec-aa95-63fd7974b705",
    "hostname": "agent-2"
  }
]


POST BASE_URI/agents/:950c5ad0-3bc3-11ec-b62a-9b0aa35e27a6/enroll

enroll 950c5ad0-3bc3-11ec-b62a-9b0aa35e27a6 (see description of enrollment request format below)

request

curl -k -sS -H "content-type: application/json" \
	-X POST 'https://minder-server:8080/agents/:950c5ad0-3bc3-11ec-b62a-9b0aa35e27a6/enroll' \
	-d '{"connection":{"mode":"connect","address":"192.168.1.1:4041"}}'

response

  • The API responds with HTTP/1.1 204 No Content on success

request

curl -k -sS -H "content-type: application/json" \
	-X POST 'https://minder-server:8080/agents/:950c5ad0-3bc3-11ec-b62a-9b0aa35e27a6/enroll' \
	-d '{"config_id":"950c5ad0-3bc3-11ec-b62a-9b0aa35e27a5"}'

response

  • The API responds with HTTP/1.1 204 No Content on success

Reading agent files synchronization state

Table 30. agents/sync/state
method + URI description

GET BASE_URI/agents/sync/state?filter=<filter expression>

get the synchronization state of all tracked files of the agents matching the specified filter or all agents should no filter be given

request

curl -k -sS -G 'https://minder-server:8080/agents/sync/state' --data-urlencode 'filter=synced=no'

response

[
  {
    "status": "success",
    "uid": "3561fbfd-c575-11ec-8001-58411d677fde",
    "hostname": "agent-1",
    "data": {
      "cert/.nxlog.id": "ok",
      "cert/.nxlog.id.sig": "ok",
      "cert/agent-ca.pem": "ok",
      "cert/agent-cert.pem": "ok",
      "cert/agent-key.pem": "ok",
      "conf/managed.conf": "modified on both minder and agent",
      "conf/addons.conf": "modified on minder",
      "conf/routes.conf": "modified on agent"
    }
  }
]


GET BASE_URI/agents/:950c5ad0-3bc3-11ec-b62a-9b0aa35e27a6/sync/state

get the synchronization state of the all tracked files of 950c5ad0-3bc3-11ec-b62a-9b0aa35e27a6

request

curl -k -sS -G 'https://minder-server:8080/agents/:950c5ad0-3bc3-11ec-b62a-9b0aa35e27a6/sync/state'

response

{
  "cert/.nxlog.id": "ok",
  "cert/.nxlog.id.sig": "ok",
  "cert/agent-ca.pem": "ok",
  "cert/agent-cert.pem": "ok",
  "cert/agent-key.pem": "ok",
  "conf/managed.conf": "modified on both minder and agent",
  "conf/addons.conf": "modified on minder",
  "conf/routes.conf": "modified on agent"
}


Reading agent synchronized file contents variants

Table 31. agents/sync/files
method + URI description

GET BASE_URI/agents/sync/files/:acl/:name?filter=<filter expression>

get the contents variants of the file specified by acl and name of the agents matching the specified filter or all agents should no filter be given

request

curl -k -sS -G 'https://minder-server:8080/agents/sync/files/:conf/:managed.conf' --data-urlencode 'filter=synced=no'

response

[
  {
    "status": "success",
    "uid": "3561fbfd-c575-11ec-8001-58411d677fde",
    "hostname": "agent-1",
    "data": {
      "synced": "44a89a12c63c64eea0ac8cc412180ca3f352bbd48bbabfec2d135b3b7fdd2580",
      "minder": "86de2ac56d599d5b3e08634a6f3ff1c3994ad99e96ec8369a110350365e50cdd",
      "remote": "386098ff48584bd2ce9ddf0104540e50f9ebe5163c43ff0838ea2bbde4427fdb",
      "contents": {
        "44a89a12c63c64eea0ac8cc412180ca3f352bbd48bbabfec2d135b3b7fdd2580": "LogLevel    INFO\nLogFile     %MYLOGFILE%\n\n<Extension admin>\n    Module      xm_admin\n\n    Host        192.168.1.1:4041\n    SocketType  SSL\n    CAFile      %CERTDIR%/agent-ca.pem\n    CertFile    %CERTDIR%/agent-cert.pem\n    CertKeyFile %CERTDIR%/agent-key.pem\n\n    <ACL conf>\n        Directory   %CONFDIR%\n        AllowRead   TRUE\n        AllowWrite  TRUE\n    </ACL>\n\n    <ACL cert>\n        Directory   %CERTDIR%\n        AllowRead   TRUE\n        AllowWrite  TRUE\n    </ACL>\n\n    <labels>\n        dplstate    \"enrolled\"\n    </labels>\n</Extension>\n",
        "86de2ac56d599d5b3e08634a6f3ff1c3994ad99e96ec8369a110350365e50cdd": "LogLevel    INFO\nLogFile     %MYLOGFILE%\n\n<Extension admin>\n    Module      xm_admin\n\n    Host        192.168.1.1:4041\n    SocketType  SSL\n    CAFile      %CERTDIR%/agent-ca.pem\n    CertFile    %CERTDIR%/agent-cert.pem\n    CertKeyFile %CERTDIR%/agent-key.pem\n\n    <ACL conf>\n        Directory   %CONFDIR%\n        AllowRead   TRUE\n        AllowWrite  TRUE\n    </ACL>\n\n    <ACL cert>\n        Directory   %CERTDIR%\n        AllowRead   TRUE\n        AllowWrite  TRUE\n    </ACL>\n\n    <labels>\n        dplstate    \"enrolled\"\n        group       \"foo\"\n    </labels>\n</Extension>\n",
        "386098ff48584bd2ce9ddf0104540e50f9ebe5163c43ff0838ea2bbde4427fdb": "LogLevel    INFO\nLogFile     %MYLOGFILE%\n\n<Extension admin>\n    Module      xm_admin\n\n    Host        192.168.1.1:4041\n    SocketType  SSL\n    CAFile      %CERTDIR%/agent-ca.pem\n    CertFile    %CERTDIR%/agent-cert.pem\n    CertKeyFile %CERTDIR%/agent-key.pem\n\n    <ACL conf>\n        Directory   %CONFDIR%\n        AllowRead   TRUE\n        AllowWrite  TRUE\n    </ACL>\n\n    <ACL cert>\n        Directory   %CERTDIR%\n        AllowRead   TRUE\n        AllowWrite  TRUE\n    </ACL>\n\n    <labels>\n        dplstate    \"enrolled\"\n        group       \"bar\"\n    </labels>\n</Extension>\n"
      }
    }
  }
]


GET BASE_URI/agents/:950c5ad0-3bc3-11ec-b62a-9b0aa35e27a6/sync/files/:path/:file

get the contents variants of the file specified by acl and name of 950c5ad0-3bc3-11ec-b62a-9b0aa35e27a6

request

curl -k -sS -G 'https://minder-server:8080/agents/:950c5ad0-3bc3-11ec-b62a-9b0aa35e27a6/sync/files/:conf/:managed.conf'

response

{
  "synced": "44a89a12c63c64eea0ac8cc412180ca3f352bbd48bbabfec2d135b3b7fdd2580",
  "minder": "86de2ac56d599d5b3e08634a6f3ff1c3994ad99e96ec8369a110350365e50cdd",
  "remote": "386098ff48584bd2ce9ddf0104540e50f9ebe5163c43ff0838ea2bbde4427fdb",
  "contents": {
    "44a89a12c63c64eea0ac8cc412180ca3f352bbd48bbabfec2d135b3b7fdd2580": "LogLevel    INFO\nLogFile     %MYLOGFILE%\n\n<Extension admin>\n    Module      xm_admin\n\n    Host        192.168.1.1:4041\n    SocketType  SSL\n    CAFile      %CERTDIR%/agent-ca.pem\n    CertFile    %CERTDIR%/agent-cert.pem\n    CertKeyFile %CERTDIR%/agent-key.pem\n\n    <ACL conf>\n        Directory   %CONFDIR%\n        AllowRead   TRUE\n        AllowWrite  TRUE\n    </ACL>\n\n    <ACL cert>\n        Directory   %CERTDIR%\n        AllowRead   TRUE\n        AllowWrite  TRUE\n    </ACL>\n\n    <labels>\n        dplstate    \"enrolled\"\n    </labels>\n</Extension>\n",
    "86de2ac56d599d5b3e08634a6f3ff1c3994ad99e96ec8369a110350365e50cdd": "LogLevel    INFO\nLogFile     %MYLOGFILE%\n\n<Extension admin>\n    Module      xm_admin\n\n    Host        192.168.1.1:4041\n    SocketType  SSL\n    CAFile      %CERTDIR%/agent-ca.pem\n    CertFile    %CERTDIR%/agent-cert.pem\n    CertKeyFile %CERTDIR%/agent-key.pem\n\n    <ACL conf>\n        Directory   %CONFDIR%\n        AllowRead   TRUE\n        AllowWrite  TRUE\n    </ACL>\n\n    <ACL cert>\n        Directory   %CERTDIR%\n        AllowRead   TRUE\n        AllowWrite  TRUE\n    </ACL>\n\n    <labels>\n        dplstate    \"enrolled\"\n        group       \"foo\"\n    </labels>\n</Extension>\n",
    "386098ff48584bd2ce9ddf0104540e50f9ebe5163c43ff0838ea2bbde4427fdb": "LogLevel    INFO\nLogFile     %MYLOGFILE%\n\n<Extension admin>\n    Module      xm_admin\n\n    Host        192.168.1.1:4041\n    SocketType  SSL\n    CAFile      %CERTDIR%/agent-ca.pem\n    CertFile    %CERTDIR%/agent-cert.pem\n    CertKeyFile %CERTDIR%/agent-key.pem\n\n    <ACL conf>\n        Directory   %CONFDIR%\n        AllowRead   TRUE\n        AllowWrite  TRUE\n    </ACL>\n\n    <ACL cert>\n        Directory   %CERTDIR%\n        AllowRead   TRUE\n        AllowWrite  TRUE\n    </ACL>\n\n    <labels>\n        dplstate    \"enrolled\"\n        group       \"bar\"\n    </labels>\n</Extension>\n"
  }
}


Agent files synchronization issue resolution commands

Table 32. agents/sync/state
method + URI description

POST BASE_URI/agents/sync/files/:acl/:name?filter=<filter expression>

execute an synchronization issue resolve operation (use_synced/use_minder/use_remote) on agents matching the specified filter or all agents should no filter be given; POST data must contain the command in json format: { "operation": "command" }

request

curl -k -sS -H "content-type: application/json" -X POST 'https://minder-server:8080/agents/sync/files/:conf/:managed.conf' --data-urlencode 'filter=synced=no' -d '{"operation":"use_minder"}'

response

[
  {
    "status": "success",
    "uid": "995a281a-3bc3-11ec-aa95-63fd7974b705",
    "hostname": "agent-2"
  }
]


POST BASE_URI/agents/:950c5ad0-3bc3-11ec-b62a-9b0aa35e27a6/sync/files/:path/:file

execute an synchronization issue resolve operation (use_synced/use_minder/use_remote) on 950c5ad0-3bc3-11ec-b62a-9b0aa35e27a6; POST data must contain the command in json format: { "operation": "command" }

request

curl -k -sS -H "content-type: application/json" -X POST 'https://minder-server:8080/agents/:950c5ad0-3bc3-11ec-b62a-9b0aa35e27a6/sync/files/:conf/:managed.conf' -d '{"operation":"use_minder"}'

response

  • The API responds with HTTP/1.1 204 No Content on success

Getting agent comment

Table 33. agents/get-comment
method + URI description

GET BASE_URI/agents/comment?filter=<filter expression>

retrieves UTF-8-encoded comment of the agents matching the specified filter or all agents should no filter be given in the response body

request

curl -k -sS -G 'https://minder-server:8080/agents/comment' --data-urlencode 'filter=name = agent-2'

response

[
  {
    "status": "success",
    "uid": "950c5ad0-3bc3-11ec-b62a-9b0aa35e27a6",
    "hostname": "agent-1",
    "data": "Some manually set comment"
  }
]


GET BASE_URI/agents/:950c5ad0-3bc3-11ec-b62a-9b0aa35e27a6/comment

retrieves UTF-8-encoded comment-8 of the agent 950c5ad0-3bc3-11ec-b62a-9b0aa35e27a6 in the response body

request

curl -k -sS -G 'https://minder-server:8080/agents/:950c5ad0-3bc3-11ec-b62a-9b0aa35e27a6/comment'

response

Some manually set comment


Setting agent comment

Table 34. agents/set-comment
method + URI description

PUT BASE_URI/agents/comment?filter=<filter expression>

set UTF-8-encoded comment of agents matching the specified filter or all agents should no filter be given

request

curl -k -sS -X PUT 'https://minder-server:8080/agents/comment?filter=name+%3D+agent-1' -d 'Some manually set comment'

response

[
  {
    "status": "success",
    "uid": "950c5ad0-3bc3-11ec-b62a-9b0aa35e27a6",
    "hostname": "agent-1"
  }
]


PUT BASE_URI/agents/:950c5ad0-3bc3-11ec-b62a-9b0aa35e27a6/comment

set UTF-8-encoded comment of agent 950c5ad0-3bc3-11ec-b62a-9b0aa35e27a6

request

curl -k -sS -X PUT 'https://minder-server:8080/agents/:950c5ad0-3bc3-11ec-b62a-9b0aa35e27a6/comment' -d 'Some manually set comment'

response

  • The API responds with HTTP/1.1 204 No Content on success

  • The API responds with HTTP/1.1 404 Not Found if the agent is unknown to NXLog Agent Minder

Deleting agent comment

Table 35. agents/delete-comment
method + URI description

DELETE BASE_URI/agents/comment?filter=<filter expression>

delete UTF-8-encoded comment of agents matching the specified filter or all agents should no filter be given

request

curl -k -sS -X DELETE 'https://minder-server:8080/agents/comment?filter=name+%3D+agent-1'

response

[
  {
    "status": "success",
    "uid": "950c5ad0-3bc3-11ec-b62a-9b0aa35e27a6",
    "hostname": "agent-1"
  }
]


DELETE BASE_URI/agents/:950c5ad0-3bc3-11ec-b62a-9b0aa35e27a6/comment

delete UTF-8-encoded comment of agent 950c5ad0-3bc3-11ec-b62a-9b0aa35e27a6

request

curl -k -sS -X DELETE 'https://minder-server:8080/agents/:950c5ad0-3bc3-11ec-b62a-9b0aa35e27a6/comment'

response

  • The API responds with HTTP/1.1 204 No Content on success

  • The API responds with HTTP/1.1 404 Not Found if the agent is unknown to NXLog Agent Minder

NXLog Agent Minder MQL Filter Syntax

Agents can be targeted individually or in sets using Minder Query Language (MQL). MQL expressions search the connected agents using the attributes provided in their serverinfo response data. To apply a query to any HTTP endpoint described above, simply include it in the URI query filter attribute.

The general format of a filter expression is as follows:

attribute operation literal

Expressions may be combined using the and, or, and not operators and can be grouped with parentheses. For example: name = agentname and not (os = Linux or digest like abcd%).

Literals may be grouped in lists with elements separated by commas and optionally delimited by parentheses. For example: name = (agent-1, agent-2, agent-3) returns the same agents as name = agent-1 or name = agent-2 or name = agent-3. Including the parentheses surrounding the list items is a stylistic choice.

String literals may be delimited by double quotes or single quotes, however this is optional. Should a string literal not be delimited, whitespace, commas, and closing parentheses will terminate the string left unescaped with the backslash character. Should it be delimited, only a matching double quote or single quote left unescaped will terminate the string.

Should a literal be interpretable as an IP address, socket address, or IP network, it will not work with string operations such as like or regex without being placed inside double or single quotes.
String literals in a query are case-sensitive.

All operations may be negated directly. For example: name not = agentname works in place of not name = agentname. Furthermore, the not keyword left in place of an operation expands to not =.

Supported Attributes

Attributes of most types may be coerced to strings such that you can use like and regex with them.
Table 36. attributes table
attribute description valid operations example

uid

The uid of the agent

=, in

uid=95d2ced5-5d6e-11ec-8000-36c209cb438d

name

The name of the agent

=, like, regex, in

name=agentname

ip

The apparent IP address of the agent

=, in

ip=192.168.0.1

socket

The agent’s remote socket address

=, in

socket=172.18.0.4:59348

local_ip

The IP address of the agent’s local socket

=, in

local_ip=172.18.0.4

local_socket

The agent’s local socket address

=, in

local_socket=172.18.0.2:4041

os

The reported operating system of the agent

=, like, regex, in

os=linux

version

The NXLog Enterprise Edition agent’s version number

=, like, regex, in

version=5.1.6133

network

The apparent network the agent is part of (exact match only)

=

network=192.168.0.0/24

module

The canonical name of the module

=, like, regex, in

module=o_udp

label

The name and value of the label provided by the agent. See the examples for details

=, like, regex, in

label=name to match on the presence of a label with name name (exact match)

label@name = value to match label with name name and value value

state

The state of the agent (ok or a string like warning: agent has no certificate, error: agent should be enrolled to persist its id and signature)

=, like, regex, in

state=error

digest

The agent’s certificate sha256 digest formatted as lowercase hex

=, in

digest=108dbb8d0c03ff7cb8d6052c89242286f48be3f6709cd4da1a8b0655d884c749

synced

The agent’s synchronization status. Set to yes if synchronized, no otherwise.

=, like, regex, in

synced=yes

config_id

The id of the agent’s assigned templated configuration

=, in

config_id=95d2ced5-5d6e-11ec-8000-36c209cb438d

config_synced

If the agent has an assigned config, and it matches with the version Minder stores, then it is set to yes, no otherwise.

=, like, regex, in

config_synced=yes

online

The agent’s online availability status. Set to yes if online, no if offline.

=, like, regex, in

online=yes

persist

The agent’s persistence status. Persistence means that the agent has a persistent uid and is retained in the inventory if disconnected. It is set when the persist_id or enrollment operation is invoked. Set to yes if persist, no otherwise.

=, like, regex, in

persist=yes

enrolled

The agent’s enrollment flag status. It is set when the enrollment operation is invoked. Set to yes if enrolled, no otherwise.

=, like, regex, in

enrolled=yes

Supported Operations

=

Checks for an exact equality

like

Checks for a match with a string pattern similar to that of SQL. An unescaped _ will act as a wildcard and allow any character. An unescaped % will allow any number of any character. This may be used to check whether an attribute starts with, ends with, or contains a pattern.

regex

Checks for a regex match

in

Checks whether the attribute is in a given container. This allows you to check whether an attribute is found in a list of literals eg. name in (agent-1, agent-2), but it also allows searching within networks eg. ip in 192.168.1.0/24.

NXLog Agent Minder Enrollment Request Format

Table 37. top level object
field description format

certificate

optional parameters for agent’s certificate generation

see description of the certificate object below

connection

mandatory connection options of the agent

see description of the connection object below

confdir-path

optional path to the conf ACL for the agents that use non-standard conf ACL path

string containing path to the conf ACL

certdir-path

optional path to the cert ACL for the agents that use non-standard cert ACL path

string containing path to the cert ACL

extra-params

optional collection of additional xm_admin module parameters.

object with keys representing additional parameter names and values representing parameter values; note that the values are saved as is and no quotation is added

extra-ro-acls

optional collection of additional read-only ACLs.

object with keys representing ACL names and values representing ACL Directory; note that the values are saved as is and no quotation is added; names must be unique across all ACLs

extra-wo-acls

optional collection of additional write-only ACLs.

object with keys representing ACL names and values representing ACL Directory; note that the values are saved as is and no quotation is added; names must be unique across all ACLs

extra-rw-acls

optional collection of additional ACLs with both read and write access.

object with keys representing ACL names and values representing ACL Directory; note that the values are saved as is and no quotation is added; names must be unique across all ACLs

extra-labels

optional collection of additional labels.

object with keys representing label names and values representing label values; note that the values are saved as is and no quotation is added

Table 38. certificate object
field description format

common-name

optional common name (CN) of the agent’s certificate subject field

string; agent’s hostname is used if this field is unspecified or null

country

optional country (C) of the agent’s certificate subject field

string containing two-letter country code; country (C) is not set if this field is unspecified or null

state

optional state (ST) of the agent’s certificate subject field

string; state (ST) is not set if this field is unspecified or null

locality

optional locality (L) of the agent’s certificate subject field

string; locality (L) is not set if this field is unspecified or null

organization

optional organization (O) of the agent’s certificate subject field

string; organization (O) is not set if this field is unspecified or null

organization-unit

optional organization unit (OU) of the agent’s certificate subject field

string; organization unit (OU) is not set if this field is unspecified or null

not-before

optional notBefore constraint of the agent’s certificate

string containing time in ASN.1, RFC3339 or RFC2822 format; notBefore constraint with the current time is used if this field is unspecified or null

not-after

optional notAfter constraint of the agent’s certificate

string containing time in ASN.1, RFC3339 or RFC2822 format; notAfter constraint of 730 days (2 years) from notBefore is used if this field is unspecified or null

serial

optional serial field of the agent’s certificate

non-negative integer; randomly generated value is used if this field is unspecified or null

encrypt_key

optional controls whether to encrypt agent’s private key (with a randomly generated password)

boolean; agent’s private key is unencrypted if this field is unspecified

Table 39. connection object
field description format

mode

mandatory connection mode of the agent

either "connect" or "listen" string

address

mandatory address to establish outgoing connection to or listen for incoming connections on

string containing NXLog Agent Minder’s IP address or hostname and agent management port in "ADDRESS:PORT" format

Minimal Enrollment Request Example

{
    "connection": {
        "mode": "connect",
        "address": "192.168.1.1:4041"
    }
}

Full Enrollment Request Example

{
    "certificate": {
        "common-name": "agent",
        "country": "US",
        "state": "CA",
        "locality": "San-Francisco",
        "organization": "NXLog",
        "organization-unit": "Dev",
        "not-before": "20200101000000Z",
        "not-after": "20201231235959Z",
        "serial": 128
    },
    "connection": {
        "mode": "connect",
        "address": "192.168.1.1:4041"
    },
    "extra-params": {
        "ReversionTimeout": "10"
    },
    "extra-ro-acls": {
        "ro-acl": "\"/var/ro\""
    },
    "extra-wo-acls": {
        "wo-acl": "\"/var/wo\""
    },
    "extra-rw-acls": {
        "rw-acl1": "\"/var/rw1\"",
        "rw-acl2": "\"/var/rw2\""
    },
    "extra-labels": {
        "first": "\"foo\"",
        "second": "\"bar\""
    }
}

Prometheus Metrics

Minder exposes Prometheus metrics on BASE_URI/metrics endpoint.

Minder provides 11 metrics for itself, 2 global metrics about agents, 13 metrics per agent and 4 metrics per module.

To get the number of data series (\(C_t\)) in the metrics store one would multiply the number of minder instances (\(C_m\)) by \(11+2\), then add the number of agents (\(C_a\)) multiplied by 13 and the number of modules (\(C_m'\)) multiplied by 4.

\[C_t=C_m*(11+2)+C_a*14+C_m'*4*C_a\]

In a concrete example, where a single minder instance serves 100 agents what have 2 modules each:

\[C_t=1*(11+2)+100*14+4*2*100\]

This comes to 2213 time series.

Metrics endpoint uses the same credentials as all other API endpoints!

Table 40. exposed metrics
metric labels description

minder_cpu_load

-

CPU load of the minder

minder_memory_usage

-

Memory usage of the minder

minder_requests

-

Total amount of requests to the minder’s API

minder_response_time

-

Histogram of response times of the minder’s API

minder_errors

-

Total amount of errors returned by the minder’s API

agents

-

Total amount of agents connected

agents_connect

-

Amount of agents connected in 'connect' mode

agents_listen

-

Amount of agents connected in 'listen' mode

agent_state

uid, hostname

Agent’s state: 0 is OK, 1 is WARNING and 2 is ERROR

agent_requests

uid, hostname

Total amount of requests to the agent

agent_response_time

uid, hostname

Histogram of response times of the agent

agent_transport_errors

uid, hostname

Total amount of transport errors while communicating with the agent

agent_cpu_load

uid, hostname

load of the agent as in RFC546

agent_memory_usage

uid, hostname

Memory usage of the agent

module_events_received

uid, hostname, module_name, module_type

Total amounts of the events received by the module of the agent

module_events_dropped

uid, hostname, module_name, module_type

Total amount of the events dropped by the module of the agent

module_events_forwarded

uid, hostname, module_name, module_type

Total amount of the events forwarded by the module of the agent

module_queue_size

uid, hostname, module_name, module_type

Queue size of the module of the agent