Configure Automatic Certificate Renewal

IDIAL includes a built-in scheduler that periodically scans the inventory and automatically renews certificates as soon as their remaining validity falls below a configurable threshold. This guide describes how to activate, configure, and monitor the scheduler.

note

The scheduler is inactive after installation. It must be explicitly activated via the API. The configuration is stored persistently and survives a container restart.

Prerequisites

All managed devices are registered in the inventory (see Register GDS Push Device)
A PKI endpoint is assigned to each device (see Configure PKI Endpoint)
API key is available

Step 1 — Check Current Scheduler Status

First, check the current state of the scheduler:

curl -s \
  -H "X-API-Key: <api-key>" \
  https://<idial-host>:5000/systeminfo

The response contains all scheduler-related fields:

{
  "software": "IDIAL",
  "version": "1.x.x",
  "gds_push_scheduler_status": "inactive",
  "gds_push_scheduler_active": false,
  "gds_push_scheduler_renewal_days": 30,
  "gds_push_scheduler_scan_interval_sec": 60,
  "monitor_scheduler_status": "inactive",
  "monitor_scheduler_active": false,
  "monitor_scheduler_scan_interval_sec": 600,
  "show_inactive_devices": false
}

Field	Description
`gds_push_scheduler_status`	`"active"` or `"inactive"`
`gds_push_scheduler_active`	Activation flag
`gds_push_scheduler_renewal_days`	Global renewal threshold in days
`gds_push_scheduler_scan_interval_sec`	Scan interval in seconds
`show_inactive_devices`	Whether inactive devices are included in scans

Step 2 — Activate and Configure the Scheduler

The scheduler is configured via POST /systeminfo. All fields are optional — only the fields sent will be changed.

curl -s -X POST \
  -H "X-API-Key: <api-key>" \
  -H "Content-Type: application/json" \
  -d '{
    "gds_push_scheduler_active": true,
    "gds_push_scheduler_renewal_days": 30,
    "gds_push_scheduler_scan_interval_sec": 60
  }' \
  https://<idial-host>:5000/systeminfo

Parameter	Type	Default	Description
`gds_push_scheduler_active`	boolean	`false`	Enable/disable the scheduler
`gds_push_scheduler_renewal_days`	integer ≥ 0	`30`	Renew certificate when remaining validity ≤ this value (days)
`gds_push_scheduler_scan_interval_sec`	integer ≥ 1	`60`	How often the inventory is scanned (seconds)
`show_inactive_devices`	boolean	`false`	Include inactive devices in the scan

tip

A renewal_days value of 30 means IDIAL renews the certificate when fewer than 30 days of validity remain. Choose a value that leaves enough buffer for failures — at least 14 days is recommended if maintenance windows are weekly.

warning

Changes to gds_push_scheduler_renewal_days reset the internal deduplication state. This means: the next scan immediately triggers a renewal check for all affected devices.

Step 3 — Set a Device-Specific Renewal Threshold (Optional)

Individual devices can have a different renewal threshold that overrides the global renewal_days value.

curl -s -X PATCH \
  -H "X-API-Key: <api-key>" \
  -H "Content-Type: application/json" \
  -d '{
    "renewal_days": 60
  }' \
  https://<idial-host>:5000/gds/inventory/<device-id>

Set renewal_days to null to return to the global value:

curl -s -X PATCH \
  -H "X-API-Key: <api-key>" \
  -H "Content-Type: application/json" \
  -d '{
    "renewal_days": null
  }' \
  https://<idial-host>:5000/gds/inventory/<device-id>

Step 4 — Monitor the Renewal Run

After activation, the scheduler runs in the background. Check the status again to confirm it is active:

curl -s \
  -H "X-API-Key: <api-key>" \
  https://<idial-host>:5000/systeminfo

Expected response after successful activation:

{
  "gds_push_scheduler_status": "active",
  "gds_push_scheduler_active": true,
  "gds_push_scheduler_renewal_days": 30,
  "gds_push_scheduler_scan_interval_sec": 60
}

note

The scheduler has no built-in retry mechanism. If a renewal fails, the error is logged and the scheduler continues with the next device. The renewal attempt is retried in the next scan cycle as long as the certificate state has not changed.

Summary

GET /systeminfo           → Check current scheduler status
POST /systeminfo          → Activate/configure the scheduler
PATCH /gds/inventory/{id} → Set device-specific renewal_days
GET /systeminfo           → Confirm activation

Next Steps

Renew Certificate Manually — Trigger an immediate renewal
Set Up Certificate Monitoring — Actively monitor certificate status
POST /systeminfo — API Reference

Troubleshooting

Symptom	Possible Cause	Solution
`gds_push_scheduler_status` stays `"inactive"`	`gds_push_scheduler_active` was not set to `true`	Send `POST /systeminfo` with `"gds_push_scheduler_active": true`
Certificates not renewed even though threshold is reached	Device has no assigned PKI endpoint	Check and assign PKI endpoint in the inventory entry
Renewal fails, next scan does not retry	Deduplication state prevents retry	Briefly change `renewal_days` and reset it — this clears the state
Device is not scanned	`show_inactive_devices: false` and device is inactive	Activate device or set `show_inactive_devices: true`

Prerequisites​

Step 1 — Check Current Scheduler Status​

Step 2 — Activate and Configure the Scheduler​

Step 3 — Set a Device-Specific Renewal Threshold (Optional)​

Step 4 — Monitor the Renewal Run​

Summary​

Next Steps​

Troubleshooting​