diff --git a/content/api/enterprise-api-ref/host-cleanup.markdown b/content/api/enterprise-api-ref/host-cleanup.markdown new file mode 100644 index 000000000..28a3b2906 --- /dev/null +++ b/content/api/enterprise-api-ref/host-cleanup.markdown @@ -0,0 +1,82 @@ +--- +layout: default +title: Host cleanup API +--- + +The Host cleanup API removes hosts from the hub based on multiple +criteria configured in the hub settings. + +## Run hosts cleanup + +Runs all enabled cleanup stages sequentially and returns statistics for each stage. + +**URI:** https://hub.cfengine.com/api/host-cleanup + +**Method:** POST + +**Prerequisites:** + +Hosts cleanup is configured through the [hub settings][Host cleanup API#Settings] + +This endpoint is not available on a [federated reporting][Federated reporting] superhub. + +**Example request (curl):** + +```console +curl --user : \ + -X POST \ + https://hub.cfengine.com/api/host-cleanup +``` + +**Example response:** + +``` +HTTP 200 OK +{ + "deletedHostsCleanup": { + "found": 0, + "permanentlyDeleted": 0, + "failed": 0 + }, + "duplicateHostnameHostsCleanup": { + "found": 0, + "softDeleted": 0, + "permanentlyDeleted": 0, + "failed": 0 + }, + "duplicateIpHostsCleanup": { + "found": 1, + "softDeleted": 1, + "permanentlyDeleted": 0, + "failed": 0 + }, + "groupHostsCleanup": { + "found": 0, + "softDeleted": 0, + "permanentlyDeleted": 0, + "failed": 0 + }, + "InactiveHostsCleanup": { + "found": 0, + "softDeleted": 0, + "permanentlyDeleted": 0, + "failed": 0 + } +} +``` + +Each stage runs independently. If a stage fails, an `error` field with the error message +is returned in place of the counters and the remaining stages still run. A maximum of +1000 hosts is processed per stage per call. + +**Responses:** + +| HTTP response code | Description | +| ------------------ | ---------------------------------------------------- | +| 200 OK | Cleanup ran; the body contains per-stage statistics. | +| 403 Forbidden | Endpoint called on a federated reporting superhub. | + +## Settings + +The behavior of each stage is controlled by the settings keys, managed +through the [Status and settings REST API][Status and settings REST API#Update settings]. diff --git a/content/api/enterprise-api-ref/status-settings.markdown b/content/api/enterprise-api-ref/status-settings.markdown index 466edd8cf..499007d86 100644 --- a/content/api/enterprise-api-ref/status-settings.markdown +++ b/content/api/enterprise-api-ref/status-settings.markdown @@ -147,6 +147,27 @@ administrator. - **passwordExpirationAfterResetHours** _(integer)_ Specifies the number of hours after which a password must expire following a reset. Default value: `48` +- **disableAI** _(boolean)_ + Disables all AI features, including the [AI chat][AI chat API] endpoint. + Default value: `false` +- **allowLlmViewAccessToAttributesNames** _(boolean)_ + Allows the LLM used by the [AI chat][AI chat API] to receive the names of inventory attributes when generating SQL queries. When `false`, the AI chat operates without knowledge of attribute names defined on the hub. + Default value: `false` +- **deletedHostsCleanup** _(object)_ + Configuration for the deleted-hosts stage of the [Host cleanup API][Host cleanup API]. Object shape: `{ "enabled": boolean, "days": integer }`. Deleted hosts older than `days` are permanently removed when enabled. + Default value: `{ "enabled": false, "days": 90 }` +- **duplicateHostnameHostsCleanup** _(object)_ + Configuration for the duplicate-hostname stage of the [Host cleanup API][Host cleanup API]. Object shape: `{ "enabled": boolean, "completelyClear": boolean }`. When `completelyClear` is `true`, deleted duplicates are also permanently removed in the same run. + Default value: `{ "enabled": false, "completelyClear": false }` +- **duplicateIpHostsCleanup** _(object)_ + Configuration for the duplicate-IP stage of the [Host cleanup API][Host cleanup API]. Object shape: `{ "enabled": boolean, "completelyClear": boolean }`. + Default value: `{ "enabled": false, "completelyClear": false }` +- **groupHostsCleanup** _(object)_ + Configuration for the group stage of the [Host cleanup API][Host cleanup API]. Object shape: `{ "enabled": boolean, "groupId": integer, "completelyClear": boolean }`. Every host in the given shared group is deleted when enabled. + Default value: `{ "enabled": false, "groupId": "", "completelyClear": false }` +- **inactiveHostsCleanup** _(object)_ + Configuration for the inactivity stage of the [Host cleanup API][Host cleanup API]. Object shape: `{ "enabled": boolean, "days": integer, "completelyClear": boolean }`. Hosts that have not reported in for `days` days are deleted when enabled. + Default value: `{ "enabled": false, "days": 30, "completelyClear": false }` **Example Request Body:** @@ -161,7 +182,14 @@ administrator. "minPasswordLength": 12, "passwordComplexity": 4, "passwordExpirationAfterResetHours": 24, - "enforce2FA": true + "enforce2FA": true, + "disableAI": false, + "allowLlmViewAccessToAttributesNames": true, + "deletedHostsCleanup": { "enabled": true, "days": 90 }, + "duplicateHostnameHostsCleanup": { "enabled": true, "completelyClear": false }, + "duplicateIpHostsCleanup": { "enabled": false, "completelyClear": false }, + "groupHostsCleanup": { "enabled": false, "groupId": 12, "completelyClear": false }, + "inactiveHostsCleanup": { "enabled": true, "days": 30, "completelyClear": true } } ```