Use Application Guardian Service (agd) to start, stop and monitor a RobustOS application and configure its response to process exits and device events. Choose its service settings to match whether your application runs continuously or completes a single task.
Applies to: RobustOS Devices with firmware that includes agd and svctrl, using a matching SDK. The baseline requirement is RobustOS 5.4 or later; confirm that the exact device release provides these components and the behavior your application needs. This article does not establish support for every device running that version.
The SDK lifecycle script and agd are different ways to manage an application:
| Application integration | Lifecycle entry point |
|---|---|
| Traditional SDK application | A packaged sdk.sh installed under /etc/sdk/<package-name> |
| Application managed by Guardian Service | A .service configuration installed in /etc/agd/ |
The traditional script exposes handlers such as start, stop, restart, status, on_startup, on_reboot, on_link_up, on_link_down, and status_sync. Use the complete Hello World lifecycle script as a reference for their dispatch structure. The example's program runs once and exits; a process-based status check can therefore report stopped after a successful run.
When migrating to agd, remove that application's traditional SDK lifecycle script from its integration so that both mechanisms do not attempt to manage the same application. Make the change as part of the application's package and deployment procedure. Do not remove another application's script or assume that deleting a source file updates an already installed device.
agd monitors the configured application's processes and can restart the application when the selected termination condition occurs. It uses cgroups to track the application's process group and subreaper behavior to adopt orphaned child processes. These mechanisms help manage lifecycle; they do not define a general security isolation or resource-limit policy for your application.
Start with the sample_agd package included in a compatible SDK. Confirm that the device firmware supplies both agd and its svctrl command before using this path.
Create a plain-text file with a .service extension in the device's /etc/agd/ directory through your application's packaging and deployment process. The file uses a [service] section with key/value settings; it is not XML.
The following is a minimal adaptation for an application whose verified start command is /usr/bin/myapp --run. Replace the name and command with the application you actually package:
[service]
name = my_application
execStart = /usr/bin/myapp --run
enforce = 1
notify = 0
oneshot = 0
This example does not configure a custom stop command. Without execStop, the service can forcibly terminate its managed process. If the application needs graceful shutdown, provide and test its appropriate stop command before relying on this configuration.
| Setting | Meaning |
|---|---|
name |
Unique application/service name; required |
execStart |
Command that starts the application; required |
execStartPost |
Optional command executed after application start |
execStop |
Optional stop command; when omitted, the process is forcibly terminated |
configApply |
Command executed when applying application configuration |
Choose a stop command that correctly identifies and stops this application's process or process group. Do not assume a process name is accepted wherever a command expects a PID. The correct command depends on your application and the utilities on the target firmware.
| Setting | Meaning |
|---|---|
linkUp / linkDown |
Optional commands for the main link's connected/disconnected events |
backupLinkUp / backupLinkDown |
Optional commands for the backup link's connected/disconnected events |
dependency |
Services that must start before this service; the example syntax is dependency = app1 app2 |
Use the service names actually installed on the device. The dependency setting describes startup ordering; it does not establish that a peer application's business operation, network session, or external server is ready.
| Setting | Meaning |
|---|---|
enforce = 0 |
Restart when all child processes of the service have terminated |
enforce = 1 |
Restart when any process in the service's process group terminates |
oneshot = 1 |
The application is intended to run once and exit |
notify = 0 |
Status becomes running when the main process starts |
notify = 1 |
Status remains starting until the application sends the required notification |
coredump = 0 / coredump = 1 |
Disable/enable generation of a core-dump file when the service crashes |
For the one-shot Hello World program, choose a one-shot lifecycle if managing it with agd. Otherwise, an ordinary successful exit can trigger restart attempts. A long-running service uses a different completion expectation.
Use notify = 1 only after implementing the notification mechanism and message format from the matching SDK example. Before deployment, check the release-specific default values, restart delay, retry limits, dependency-failure behavior, core-dump location and persistence across reboot; these are not specified by the settings listed here.
After installing or editing your service file, use the device shell to reload configurations, list registered services, and inspect the intended service:
svctrl --reload
svctrl --list
svctrl --status <app_name>
Replace <app_name> with the configured name. --reload reloads all application configuration files; account for other service-file changes waiting on that device before using it.
| Command | Effect |
|---|---|
svctrl --start <app_name> |
Start the specified application |
svctrl --stop <app_name> |
Stop the application |
svctrl --restart <app_name> |
Restart the application |
svctrl --status <app_name> |
Show its status, such as running, stopped, or starting |
svctrl --list |
List managed applications and their current status |
svctrl --reload |
Reload all application service configurations |
svctrl --mask <app_name> |
Prevent the application from being started while masked |
svctrl --unmask <app_name> |
Remove the mask so normal operation can resume |
On a development device, test normal start/stop, the selected process-exit condition, one-shot completion if relevant, and readiness notification if enabled. Observe the service status and application log together. Do not infer automatic-recovery success merely because the service initially reaches running.
Confirm that only the intended lifecycle manager controls the application. Test start, stop, restart, configuration application and the relevant link events on the development device. For an existing installation, verify that package changes also remove or replace the old lifecycle integration as intended.
Record the service file, firmware, SDK and application versions with the results. If readiness notification or restart recovery is required, observe those transitions directly in svctrl status and the application log. Reaching running once does not demonstrate recovery after a later exit. Include a device restart test when the application must start automatically after reboot.