What is the AGS engine; what does the Engine screen show?

Short answer

The AGS engine is the component that handles the login pages, the authentication and MFA steps and the access flow of an AGS-enabled vService; it runs separately on each device for each AGS-enabled vService. The application requests of a user whose session is authenticated go to the Backend Service without passing through the engine. The Engine tab of the vService shows one card for each device: the status badge (running, partially degraded, starting, not responding, restarting repeatedly (crash loop), stopped, not created, unknown), the reason row if there is one, and the Uptime, Memory and Storage measurements. Restart Engine restarts the engine on the device of the card without deleting the session, lockout and TOTP records; Clean Storage irreversibly deletes all the sessions, lockouts, TOTP records and counters that belong to the vService on that device. While the engine is not ready, visitors see the page with the text "Access Gateway is being prepared".

How Does It Work?

1. When AGS is enabled on a vService, an AGS engine starts running for that vService on each device.
2. Requests that have no session and the login, MFA and portal pages under AGS Root Path are handled by the engine.
3. Sessions, lockouts and TOTP records are kept in the session store of the device; the requests of a user with a valid session are forwarded directly to the Backend Service without passing through the engine.
4. If the engine cannot respond, the page with the text "Access Gateway is being prepared. Please try again shortly." is returned to the requests the engine handles.

The Engine Tab in TR7

Card item	What it shows
Status badge	running (green) · starting, partially degraded (yellow) · not responding, restarting repeatedly (crash loop), stopped, not created (red) · unknown (the status could not be retrieved)
Reason row	engine files are missing on this device, ran out of memory, engine setup failed, session storage is unreachable
Uptime	The running time of the engine; it is reset on a restart
Memory	The memory used and its limit; the limit is half of the Memory Limit value of the vService, and 1 GB if Memory Limit is not selected
Storage	The space used for this vService in the session store

• The operations are per device: Restart Engine and Clean Storage are applied only to the device of the card that is clicked; in a cluster, the other device is not affected. The operations ask for confirmation and are written to the User Logs screen.
• During Restart Engine: Visitors who have not logged in see the preparation page; users whose session is open continue to access the application.
• Alarm: When the engine goes into an unhealthy state, an engine status alarm is produced; the alarm is sent as an interface notification if no profile is selected, and with the Notification Profiles channels if a profile is selected.
• Memory: If ran out of memory appears under the badge, the Memory Limit in the QOS settings of the vService is raised; this change restarts the vService and the open connections are cut.

Common Misconceptions

• "Restart Engine deletes the sessions." Sessions, lockouts and TOTP records remain in the session store; only Clean Storage deletes this data.
• "Clean Storage resets the AGS configuration." The flow, the profiles, the local user databases and the Audit Logs records are not affected; what is deleted is the session store data on that device. Users log in again, and TOTP users enroll their authenticator again.
• "If the engine stops, even users who have logged in cannot access the application." The application requests of a user with a valid session do not pass through the engine; what is affected are the requests the engine handles, such as login and MFA.
• "In a cluster, Restart Engine runs on both devices at once." Each card applies to its own device; the operation is run separately for the two devices.

How it is done in the documentation

• Engine · What Is Engine?
• Engine · Card Header
• Engine · Card Buttons
• Engine · Scope and Limits

Related questions

• Which monitoring screens does AGS have; what does each one show?
• What are log forwarding and notification profiles for in AGS?
• What happens to traffic when AGS is enabled on a vService?
• How do AGS sessions and settings behave in a cluster?