Support

NXLog Documentation

NXLog Agent Minder Public APIs

Counting agents

Table 1. agents/count
method + URI description

GET BASE_API_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/api/v0.5/agents/count' --data-urlencode 'filter=os = Linux'

response

5

Listing agents

Table 2. agents/ids
method + URI description

GET BASE_API_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/api/v0.5/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_API_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/api/v0.5/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": {},
      "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_API_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/api/v0.5/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": {},
  "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_API_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/api/v0.5/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,
      "events_per_second": 20,
      "modules": {
        "input": {
          "events_received": 0,
          "events_dropped": 0,
          "events_forwarded": 10,
          "events_per_second": 10,
          "queue_limit": 100,
          "queue_size": 0,
          "batch_size": 50
        },
        "output": {
          "events_received": 10,
          "events_dropped": 0,
          "events_forwarded": 0,
          "events_per_second": 10,
          "queue_limit": 100,
          "queue_size": 0,
          "batch_size": 50
        }
      },
      "routes": {
        "route": {
          "events_received": 10,
          "events_dropped": 0,
          "events_forwarded": 10,
          "events_per_second": 20
        }
      }
    }
  }
]

GET BASE_API_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/api/v0.5/agents/:950c5ad0-3bc3-11ec-b62a-9b0aa35e27a6/stats'

response

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

Agent commands

Table 5. agents
method + URI description

POST BASE_API_URI/agents?filter=<filter expression>

execute an agent operation (start/restart/stop/persist_id/refresh) 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"}. In case of the set_config operation, a config_id field is required. config_id can refer to both templates and configurations.

request

curl -k -sS -H "content-type: application/json" -X POST 'https://minder-server:8080/api/v0.5/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/api/v0.5/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_API_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/api/v0.5/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/api/v0.5/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_API_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/api/v0.5/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_API_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/api/v0.5/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_API_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/api/v0.5/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,
      "events_per_second": 10,
      "queue_limit": 100,
      "queue_size": 0,
      "batch_size": 50
    }
  }
]

GET BASE_API_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/api/v0.5/agents/:950c5ad0-3bc3-11ec-b62a-9b0aa35e27a6/modules/:module1/stats'

response

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

Module commands

Table 8. agents/modules
method + URI description

POST BASE_API_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/api/v0.5/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_API_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/api/v0.5/agents?filter=name+%3D+agent-1'

response

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

DELETE BASE_API_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/api/v0.5/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_API_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. The content will be encoded with base64 encoding if the file will not be UTF-8 compatible.

request for a UTF-8 file

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

response for a UTF-8 file

[
  {
    "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</Extension>\n"
  }
]

request for a non-UTF-8 file

curl -k -sS -G 'https://minder-server:8080/api/v0.5/agents/files/:someacl/:somebinaryfile' --data-urlencode 'filter=name = agent-2'

response for a non-UTF-8 file

[
  {
    "status": "success",
    "uid": "995a281a-3bc3-11ec-aa95-63fd7974b705",
    "hostname": "agent-2",
    "encoding": "base64",
    "data": "8PHy8/T19vf4+fr7/P79/w=="
  }
]

GET BASE_API_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 without any encoding.

request

curl -k -sS -G 'https://minder-server:8080/api/v0.5/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>
</Extension>

Writing files

Table 11. agents/files
method + URI description

PUT BASE_API_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/api/v0.5/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_API_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/api/v0.5/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_API_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/api/v0.5/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_API_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_API_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. The content will be encoded with base64 encoding if the file will not be UTF-8 compatible.

request

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

response for a UTF-8 config

[
  {
    "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        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>"
  }
]

response for a non-UTF-8 config

[
  {
    "status": "success",
    "uid": "950c5ad0-3bc3-11ec-b62a-9b0aa35e27a6",
    "hostname": "agent-1",
    "encoding": "base64",
    "data": "8PHy8/T19vf4+fr7/P79/w=="
  }
]

GET BASE_API_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/api/v0.5/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>
        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_API_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/api/v0.5/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_API_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/api/v0.5/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.

Exporting agents

Table 15. agents/export
method + URI description

GET BASE_API_URI/agents/export?filter=<filter expression>

return config files, keys and certificates of the agents matching the specified filter or all agents should not filter be given

request

curl -k -sS -G 'https://minder-server:8080/api/v0.5/agents/export' --data-urlencode 'filter=name = agent-1' --output agents-configs.zip

response

agents-configs.zip
└── agent_agent-1_950c5ad0-3bc3-11ec-b62a-9b0aa35e27a6
    ├── cert
    │   ├── agent-ca.pem
    │   ├── agent-cert.pem
    │   ├── agent-key.pem
    │   ├── .nxlog.id
    │   └── .nxlog.id.sig
    └── conf
        └── managed.conf

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

return config files, keys and certificates of the agent with id 950c5ad0-3bc3-11ec-b62a-9b0aa35e27a6

request

curl -k -sS -G 'https://minder-server:8080/api/v0.5/agents/:950c5ad0-3bc3-11ec-b62a-9b0aa35e27a6/export' --output agent_agent-1_950c5ad0-3bc3-11ec-b62a-9b0aa35e27a6.zip

response

agent_agent-1_950c5ad0-3bc3-11ec-b62a-9b0aa35e27a6.zip
└── agent_agent-1_950c5ad0-3bc3-11ec-b62a-9b0aa35e27a6
    ├── cert
    │   ├── agent-ca.pem
    │   ├── agent-cert.pem
    │   ├── agent-key.pem
    │   ├── .nxlog.id
    │   └── .nxlog.id.sig
    └── conf
        └── managed.conf

Reading agent state

Table 16. agents/state
method + URI description

GET BASE_API_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/api/v0.5/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_API_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/api/v0.5/agents/:950c5ad0-3bc3-11ec-b62a-9b0aa35e27a6/state'

response

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

Templates and configurations overview

NXLog Agent Minder provides the opportunity to manage agent configuration in a modular manner. Administrators can define textual templates, and assign them to agents directly, or define configurations to combine multiple templates. API endpoints under /configs and /templates can be used to perform standard read, create, update and delete operations on both templates and configurations. Under /templates, only operations concerning templates can be performed, and listing endpoints (/templates/ids and /templates/names) only list templates, while endpoints under /configs only deal with configurations and list configurations.

Both templates and configurations are identified by UUIDv1 identifiers, and when assigning them to agents, the config-id field works with both template & configuration ids.

NXLog Agent Minder executes validation steps when templates and configurations are posted, updated, assigned to agents, or used in auto-enroll rules. A template or configuration assigned to an agent or used in an auto-enroll rule is considered to be in use. Validation requirements differ based on usage. We do not expect all templates to be fully functional until they are about to be used, as they might be made parts of configurations. Modules and routes can be defined separately, but when a configuration containing them is about to be used, a complete validation is executed. This checks, among other things, that modules are used on paths consistently (each module used on a path is defined, and is in a position that matches it’s type), and an xm_admin extension module is present, which specifies how the agent will connect to NXLog Agent Minder. It is therefore possible that a template can be posted successfully, but cannot be used for enrollment if complete validation fails.

Adding a new configuration template

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

Table 17. templates/adding
method + URI description

POST BASE_API_URI/templates

add a new template

request

curl -k -sS -H "content-type: application/json" -X POST \
    'https://minder-server:8080/api/v0.5/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 18. templates/ids
method + URI description

GET BASE_API_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/api/v0.5/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 19. templates/ids_names
method + URI description

GET BASE_API_URI/templates/names

get a list of template uuids and corresponding names

request

curl -k -sS -G 'https://minder-server:8080/api/v0.5/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 20. templates/retrieving
method + URI description

GET BASE_API_URI/templates/:template_id

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

request

curl -k -sS -G 'https://minder-server:8080/api/v0.5/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",
    "used_by_templates": [
        "c0bbed0b-3463-43af-bfff-68e1964f7310"
    ],
    "used_by_agents": [
        "e417260d-6ee9-42e6-a99b-68b2dcca5c01",
        "067d18c7-4d44-4cd0-902d-ada59391f64b"
    ],
    "used_by_autoenroll_rules": [
        "5a9b2370-e321-48b0-b2bf-af16e0da0dd7"
    ],
    "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 21. templates/updating
method + URI description

PUT BASE_API_URI/templates/:template_id

update a template

request

curl -k -sS -H "content-type: application/json" -X PUT 'https://minder-server:8080/api/v0.5/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://minder-server:8080/api/v0.5/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://minder-server:8080/api/v0.5/templates/:1833a995-f5eb-11ec-8000-b41973229aaa' -d '{ "name": "updated name" }'
curl -k -sS -H "content-type: application/json" -X PUT 'https://minder-server:8080/api/v0.5/templates/:1833a995-f5eb-11ec-8000-b41973229aaa' -d '{ "comment": "updated comment" }'
curl -k -sS -H "content-type: application/json" -X PUT 'https://minder-server:8080/api/v0.5/templates/:1833a995-f5eb-11ec-8000-b41973229aaa' -d '{ "comment": null }'

Removing a configuration template

Table 22. templates/deleting
method + URI description

DELETE BASE_API_URI/templates/:template_id

remove a template

request

curl -k -sS -X DELETE 'https://minder-server:8080/api/v0.5/templates/:1833a995-f5eb-11ec-8000-b41973229aaa'

Adding a configuration

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

Table 23. configurations/adding
method + URI description

POST BASE_API_URI/configs/

add a configuration

request

curl -k -sS -H "content-type: application/json" -X PUT 'https://minder-server:8080/api/v0.5/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 24. configurations/listing
method + URI description

`GET BASE_API_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/api/v0.5/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 25. configurations/listing_ids_and_names
method + URI description

`GET BASE_API_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/api/v0.5/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 26. configurations/get
method + URI description

`GET BASE_API_URI/configs/:config_id

return the configuration referenced by the given config_id

request

curl -k -sS -G 'https://minder-server:8080/api/v0.5/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 27. configurations/get_contents
method + URI description

`GET BASE_API_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/api/v0.5/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 28. configurations/updating
method + URI description

PUT BASE_API_URI/configs/:config_id

update an existing configuration

request

curl -k -sS -H "content-type: application/json" -X PUT 'https://minder-server:8080/api/v0.5/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://minder-server:8080/api/v0.5/configs/:1833a995-f5eb-11ec-8000-b41973229aaa'
    -d '{ "name": "name updated" }'

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

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

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

Remove a configuration

Table 29. configurations/deleting
method + URI description

DELETE BASE_API_URI/configs/:config_id

remove an existing configuration

request

curl -k -sS -X DELETE 'https://minder-server:8080/api/v0.5/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 template or configuration.

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

method + URI

description

POST BASE_API_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/api/v0.5/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_API_URI/agents/:950c5ad0-3bc3-11ec-b62a-9b0aa35e27a6/enroll

enroll 950c5ad0-3bc3-11ec-b62a-9b0aa35e27a6 (see description of enrollment request format below). The config_id field can refer to both templates and configurations.

request

curl -k -sS -H "content-type: application/json" \
	-X POST 'https://minder-server:8080/api/v0.5/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/api/v0.5/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

Automatic enrollment

Minder provides a way to automate agent enrollment. This is done by definining 'auto-enroll rules' that can be used to enroll agents either at their connection time, or when calling the /autoenroll API endpoint. An auto-enroll rule has the following components:

  • name

  • filter

  • connection options

  • (optional) automatic flag

  • (optional) priority

  • (optional) comment

Here, filter is an MQL filter used to select the subset of agents that a particular auto-enroll rule applies to. Connection options is a set of options used to generate a configuration for the agent, identical to what is used in the /enroll endpoint: it can either be a specification of connection options, or a config_id of a configuration stored by Minder. Automatic flag decides if this auto-enroll rule should be used for agents at connection time (when set to true), or only when calling the /autoenroll endpoint. Defaults to false. Priority is used to select the auto-enroll rule to apply when an agent matches the filters of multiple auto-enroll rules. It is a signed integer, and defaults to zero. Comment is an arbitrary text the user can provide to describe the rule.

If an agent is not enrolled during it’s connection process, an auto-enroll error will be recorded, providing a cause of failure. This information is accessible both in agent information (/agents) and agent status (/agents/status) endpoints, and it is deleted when the agent disconnects, or following a successful enrollment via other means (either the /enroll or /autoenroll endpoints). For example, if no automatic auto-enroll rule matches the agent, but there is at least one non-automatic one that does, the agent will report an auto-enroll error until the /autoenroll endpoint is called.

Adding an auto-enroll rule

The config-id field in enrollment options can refer to both templates and configurations.

Table 31. autoenroll/adding

method + URI

description

POST BASE_API_URI/autoenroll

add an auto-enroll rule

request

curl -k -sS -H "content-type: application/json" \
	-X POST 'https://minder-server:8080/api/v0.5/agents/autoenroll' \
	-d '{
        "name": "Unfortunate Conflict of Evidence",
        "filter": "os=linux and name regex bar-.*",
        "options": {
            "config-id": "f5685a29-5359-11ed-8000-4f4a1159d71d"
        },
        "priority": -1,
        "comment": "this is important"
    }'

response

* The API responds with 'HTTP/1.1 200 Ok' on success, with the body containing the Uuid v1 of the created auto-enroll rule.

1833a995-f5eb-11ec-8000-b41973229aaa

Updating an auto-enroll rule

To update an auto-enroll rule, only the fields to be updated need to be specified. In order to delete the comment, the null JSON value can be used in the comment field.

Table 32. autoenroll/updating

method + URI

description

POST BASE_API_URI/autoenroll/:autoenroll_rule_id

update an auto-enroll rule

request

curl -k -sS -H "content-type: application/json" \
	-X POST 'https://minder-server:8080/api/v0.5/agents/autoenroll/:1833a995-f5eb-11ec-8000-b41973229aaa' \
	-d '{"filter": "os=Windows"}'

response

* The API responds with 'HTTP/1.1 204 No Content' on success, or an error detailing the reason the update failed.

Getting an auto-enroll rule

Table 33. autoenroll/getting

method + URI

description

GET BASE_API_URI/autoenroll/:autoenroll_rule_id

retrieve an auto-enroll rule

request

curl -k -sS -X GET 'https://minder-server:8080/api/v0.5/agents/autoenroll/:1833a995-f5eb-11ec-8000-b41973229aaa'

response

{
    "name": "rule's name",
    "options": {
        "config-id": "f5685a29-5359-11ed-8000-4f4a1159d71d"
    },
    "filter": "os=Windows",
    "priority": -1,
    "automatic": false,
    "add_time": "2022-10-24T07:45:07.504212940Z",
    "update_time": "2022-10-24T07:45:07.504212940Z",
    "comment": "this is important"
}

Deleting an auto-enroll rule

Table 34. autoenroll/deletion

method + URI

description

DELETE BASE_API_URI/autoenroll/:autoenroll_rule_id

delete an auto-enroll rule

request

curl -k -sS -X DELETE 'https://minder-server:8080/api/v0.5/agents/autoenroll/:1833a995-f5eb-11ec-8000-b41973229aaa'

response

* The API responds with 'HTTP/1.1 204 No Content' on success, or an error detailing the reason the update failed.

Listing auto-enroll rules

Table 35. autoenroll/listing

method + URI

description

GET BASE_API_URI/autoenroll/ids

lists the ids of currently defined auto-enroll rules

request

curl -k -sS -X GET 'https://minder-server:8080/api/v0.5/autoenroll/ids'

response

[
    "8fe39f22-5378-11ed-8002-b54590f41152",
    "906054cf-5378-11ed-8003-9540bc0518e9",
    "ca633c42-5378-11ed-8006-2a647eb4ac0e"
]

GET BASE_API_URI/autoenroll/names

lists the names and ids of currently defined auto-enroll rules as a JSON map

request

curl -k -sS -X GET 'https://minder-server:8080/api/v0.5/autoenroll/names'

response

{
    "8fe39f22-5378-11ed-8002-b54590f41152": "name of the first",
    "c7b005dc-536f-11ed-8001-c7036aa1c619": "whatever the second's called",
    "ca633c42-5378-11ed-8006-2a647eb4ac0e": "the charm"
}

Auto-enrolling agents

Calling the /agents/autoenroll endpoint tryes to enroll agents with both automatic and non-automatic enroll rules. As with other endpoints under /agents/, it allows the use of MQL filters with the ?filter query parameter. In order for an agent to get enrolled with this method, both the filter provided in with the query parameter, and the filter used to define the auto-enroll rule needs to match the agent.

Table 36. autoenroll/enrolling

method + URI

description

POST BASE_API_URI/autoenroll?filter=<filter expression>

attempts to auto-enroll agents matching the given filter

request

curl -k -sS -X POST 'https://minder-server:8080/api/v0.5/autoenroll'

response

[
    {
        "status": "success",
        "uid": "344ec3db-537d-11ed-8002-3a6a6523a749",
        "hostname": "draconian-maid-1",
        "data": "6c72b5a1-537d-11ed-8000-e832e4d8837d"
    },
    {
        "status": "failure",
        "uid": "344e9167-537d-11ed-8001-103ddab5d25b",
        "hostname": "frail-scale-1",
        "error": "no auto-enroll rule matches this agent"
    },
    {
        "status": "success",
        "uid": "344f6ea8-537d-11ed-8005-91b95ff93530",
        "hostname": "secretive-plants-1",
        "data": "6c72b5a1-537d-11ed-8000-e832e4d8837d"
    }
]

Reading agent files synchronization state

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

GET BASE_API_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/api/v0.5/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_API_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/api/v0.5/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 38. agents/sync/files
method + URI description

GET BASE_API_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/api/v0.5/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</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        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        group       \"bar\"\n    </labels>\n</Extension>\n"
      }
    }
  }
]

GET BASE_API_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/api/v0.5/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</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        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        group       \"bar\"\n    </labels>\n</Extension>\n"
  }
}

Agent files synchronization issue resolution commands

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

POST BASE_API_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/api/v0.5/agents/sync/files/:conf/:managed.conf?filter=synced=no' -d '{"operation":"use_minder"}'

response

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

POST BASE_API_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/api/v0.5/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 40. agents/get-comment
method + URI description

GET BASE_API_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/api/v0.5/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_API_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/api/v0.5/agents/:950c5ad0-3bc3-11ec-b62a-9b0aa35e27a6/comment'

response

Some manually set comment

Setting agent comment

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

PUT BASE_API_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/api/v0.5/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_API_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/api/v0.5/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 42. agents/delete-comment
method + URI description

DELETE BASE_API_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/api/v0.5/agents/comment?filter=name+%3D+agent-1'

response

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

DELETE BASE_API_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/api/v0.5/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 43. 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

status

The status of the agent, one of (ok, error, warning). error and warning cover all possible error and warning states, respectively.

=, in

status in (ok, error) to match all agents with ok or error statuses

status=ok to match all agents with ok status

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

add_time

Time when the agent was added to NXLog Agent Minder. Can be compared to time literals in one of the supported formats (see below).

<, >, <=, >=, =

add_time >= 20030701085237Z

connect_time

Time of the agent’s most recent connection. Can be compared to time literals in one of the supported formats (see below).

<, >, <=, >=, =

connect_time < '2003-07-01T08:52:37Z'

enroll_time

Time when the agent was enrolled. Can be compared to time literals in one of the supported formats (see below).

<, >, <=, >=, =

enroll_time = 030701085237Z

persist_time

Time when the agent was persisted. Can be compared to time literals in one of the supported formats (see below).

<, >, <=, >=, =

persist_time >= '030701085237Z'

poll_time

Time when the agent was last polled. Can be compared to time literals in one of the supported formats (see below).

<, >, <=, >=, =

poll_time >= "030701085237Z"

start_time

Time when the agent started. Can be compared to time literals in one of the supported formats (see below).

<, >, <=, >=, =

start_time >= 'Tue, 1 Jul 2003 10:52:37 +0200'

memory_used

The agent’s memory consumption at it’s latest poll. Can be compared to integer literals (see below).

<, >, <=, >=, =, in

memory_used > 1.5G or memory_used in (500k, 1G)

cpu_load

The agent’s CPU consumption at it’s latest poll. Can be compared to float literals (see below).

<, >, <=, >=, =, in

cpu_load > 99% or cpu_load < 0.01

events_per_second

Events processed by all of the agent’s modules per second at it’s latest poll. Can be compared to float literals (see below).

<, >, <=, >=, =, in

events_per_second >= 990k and events_per_second < 0.991M or events_per_second in (0, 1, 2.5)

Supported Operations

=

Checks for an exact equality

<, >, <=, >=

Relative comparisons: less than, greater than, less than or equal, greater than or equal. They work with time- and numeric literals.

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 Pagination query parameters

All endpoints that support setting a filter for agent filtering also allow the use the pagination query parameters. Both offset-based and cursor-based pagination approaches are supported.

Cursor-based pagination is applied first, using from, after, to and before parameters. Note that cursor-based pagination is applied before filtering with the MQL filter. Therefore, the result may not include entries specified by from or to parameters. After that, filtering is applied to the result of cursor-based pagination. Finally, the offset-based pagination is applied using offset and limit parameters to the result of cursor-based pagination and filtering.

The following parameters are supported:

parameter value type description example agents returned conflicts with

from

Uuid

The first agent that will not be skipped.

from=95cd7932-6ed0-409b-8cfc-8cec7872043e

4fdf4c8d-…​
62cd0679-…​
95cd7932-…​
d444e7ca-…​
e46d00d2-…​

after

after

Uuid

The last agent to be skipped.

after=95cd7932-6ed0-409b-8cfc-8cec7872043e

4fdf4c8d-…​
62cd0679-…​
95cd7932-…​
d444e7ca-…​
e46d00d2-…​

from

to

Uuid

The last agent to be returned.

to=95cd7932-6ed0-409b-8cfc-8cec7872043e

4fdf4c8d-…​
62cd0679-…​
95cd7932-…​
d444e7ca-…​
e46d00d2-…​

before

before

Uuid

The first agent to not be returned.

before=95cd7932-6ed0-409b-8cfc-8cec7872043e

4fdf4c8d-…​
62cd0679-…​
95cd7932-…​
d444e7ca-…​
e46d00d2-…​

to

offset

Integer

The number of agents to be skipped.

offset=2

4fdf4c8d-…​
62cd0679-…​
95cd7932-…​
d444e7ca-…​
e46d00d2-…​

 — 

limit

Integer

The maximum number of agents to return.

limit=3

4fdf4c8d-…​
62cd0679-…​
95cd7932-…​
d444e7ca-…​
e46d00d2-…​

 — 

An error is returned if:

  • from and after parameters used at same time;

  • to and before parameters used at same time;

  • the agent specified by from, after, to and before is not found;

  • the agent specified by from or after is ordered after the agent specified by to or before.

Complex pagination query examples

Request without pagination:

curl -k -sS -G 'https://minder-server:8080/api/v0.5/agents/ids'

Response:

[
  "03099bc5-6736-45c3-b3ba-aeabba48f78b",
  "16efab6f-afad-478c-8775-ab6a328735d1",
  "2844aa0c-2462-4bf6-aff5-a1c19424a92d",
  "3343dd26-18fb-44b2-9a27-3b74170e1969",
  "36a55a89-f96d-4c5f-8cd4-23907329a41e",
  "433a2dab-c0af-4ddd-978a-1649d945afaa",
  "4fdf4c8d-45e2-4c28-907a-c1a01a79080d",
  "62cd0679-ae5e-4da3-ab4e-38a50d9edfaf",
  "67e89f41-847d-4b2d-b37b-74ce30a01273",
  "85dcdacd-bd83-4595-b899-c82eb2721f92",
  "95cd7932-6ed0-409b-8cfc-8cec7872043e",
  "a74813d2-a1f7-460c-9a8b-ee1013c8e488",
  "d444e7ca-423c-4a88-9f94-8ce2f6075943",
  "e46d00d2-6c69-48fd-b756-3ab394d90c65",
  "e58edfa1-93b4-4e64-962b-10ac66fe9272",
  "e8bec679-aed5-4cb1-a3a9-8df704561e5a"
]

Request with cursor-based pagination:

curl -k -sS -G 'https://minder-server:8080/api/v0.5/agents/ids?from=2844aa0c-2462-4bf6-aff5-a1c19424a92d&before=a74813d2-a1f7-460c-9a8b-ee1013c8e488'

Response:

[
  "2844aa0c-2462-4bf6-aff5-a1c19424a92d",
  "3343dd26-18fb-44b2-9a27-3b74170e1969",
  "36a55a89-f96d-4c5f-8cd4-23907329a41e",
  "433a2dab-c0af-4ddd-978a-1649d945afaa",
  "4fdf4c8d-45e2-4c28-907a-c1a01a79080d",
  "62cd0679-ae5e-4da3-ab4e-38a50d9edfaf",
  "67e89f41-847d-4b2d-b37b-74ce30a01273",
  "85dcdacd-bd83-4595-b899-c82eb2721f92",
  "95cd7932-6ed0-409b-8cfc-8cec7872043e"
]

Request with cursor-based and offset-based pagination:

curl -k -sS -G 'https://minder-server:8080/api/v0.5/agents/ids?from=2844aa0c-2462-4bf6-aff5-a1c19424a92d&to=a74813d2-a1f7-460c-9a8b-ee1013c8e488&offset=3&limit=4'

Response:

[
  "433a2dab-c0af-4ddd-978a-1649d945afaa",
  "4fdf4c8d-45e2-4c28-907a-c1a01a79080d",
  "62cd0679-ae5e-4da3-ab4e-38a50d9edfaf",
  "67e89f41-847d-4b2d-b37b-74ce30a01273"
]

Supported time formats

All examples in this section represent the time 1 Jul 2003 08:52:37 GMT.

Time literals that contain spaces (eg. Tue, 1 Jul 2003 10:52:37 +0200) need to be placed inside single or double quotes.
ASN.1

These take the form of YYMMDDhhmm[ss]Z or YYYYMMDDhhmm[ss]Z where the letter 'Z' indicates UTC time. Examples are 030701085237Z and 20030701085237Z, respectively.

Currently ASN.1 times with time zone offsets other than Z are not supported.
RFC3339

These take the form of {YYYY}-{MM}-{DD}T{hh}:{mm}:{ss}Z or {YYYY}-{MM}-{DD}T{hh}:{mm}:{ss}+{hh}:{mm}. Here, the letter 'Z' indicates UTC time, which can be replaced with a relative offset of hours and minutes. Examples are 2003-07-01T08:52:37Z and 2003-07-01T10:52:37+02:00, respectively.

RFC2822

These take the form of Day, [D]D Mon YYY hh:mm:ss TZ or Day, [D]D Mon YYY hh:mm:ss +hhmm. Here, TZ represents the time zone (for example GMT), which can be replaced by an explicit offset of hours and minutes. Examples are 'Tue, 1 Jul 2003 08:52:37 GMT' or 'Tue, 1 Jul 2003 10:52:37 +0200', respectively.

Supported numeric literals

MQL supports numeric literals with suffixes in in expressions and comparison operations. The following suffixes are supported.

k

kilo: 1.5k equals 1500

M

mega: 1.5M equals 1500000

G

giga: 1.5G equals 1500000000

%

percent: 50% equals 0.5

Some attributes can only be compared to integer literals (eg. memory_used), while others expect float literals (eg. cpu_load).

NXLog Agent Minder Enrollment Request Format

Table 44. 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 45. 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
connection object

address and addresses are mutually exclusive, only one of them needs to be specified.

field description format

mode

mandatory connection mode of the agent

either "connect" or "listen" string

address

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

addresses

Multiple addresses. Agents will try to connect to them in the specified order, and use the remaining ones as fallback. Can only be used with connect mode.

vector of strings containing IP addresses or hostnames and agent management ports in "ADDRESS:PORT" format

Minimal Enrollment Request Examples

{
    "connection": {
        "mode": "connect",
        "address": "192.168.1.1:4041"
    }
}
{
    "connection": {
        "mode": "connect",
        "addresses": ["test.example.com:4043", "[::1]:4041", "127.0.0.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_API_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 46. 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

© Copyright NXLog Ltd.

PRIVACY POLICY TERMS OF USE