Session Agent
The agent runs as a system service, so it cannot see a user’s desktop.
The session agent (nxsagent) is a small helper that runs inside each user’s desktop session and does the work that needs that session: it takes screenshots and reports the session’s user, display, and screen size.
The session agent does not show anything to the user. For menus, notifications, and desktop customization, use the User Support Application (see User Support Application Notifications); when it starts in a session, the agent stops the session agent running in the same session, because the User Support Application does the same work.
On Linux systems without a desktop session, the fbdev subagent takes screenshots from the framebuffer instead; see Framebuffer Screenshots.
Installation
The session agent is started by the desktop session at login, not by the agent.
-
Linux: install the
netxms-agent-sessionpackage. It installs/usr/bin/nxsagentand an autostart entry in/etc/xdg/autostart/, so the session agent starts in each graphical session at the next login. -
Windows: select the Install session agent task in the agent installer (task name
sessionagentfor/MERGETASKS, see Windows Agent Installer Reference). The installer addsnxsagent.exe -Hto the programs that Windows starts at every user login.
Connection to the Agent
The session agent connects to the agent at 127.0.0.1, TCP port 28180, and tries again every 30 seconds until it succeeds.
The agent listens on that port when SessionAgentPort has its default value; SessionAgentPort = 0 turns the listener off.
The session agent always uses port 28180, so do not change SessionAgentPort to another port.
To see the connected session agents, check the Agent.SessionAgentCount metric and the Agent.SessionAgents table (session ID and name, user, state, process ID, and screen size); see Agent Metrics.
Screenshots
A screenshot request names the session to capture:
-
On Windows, the session name is the Windows session name; the local desktop is
Console. -
On Linux, the session name is the value of
DISPLAY(such as:0), or ofWAYLAND_DISPLAYwhenDISPLAYis not set, orConsolewhen neither is set;Agent.SessionAgentsshows it. -
On Linux with the
fbdevsubagent, the session namesfb0tofb7select a framebuffer device; see Framebuffer Screenshots.
The management client offers Take screenshot only for Windows nodes; it captures the Console session, or the first connected session agent if there is no Console session.
For other sessions or for Linux nodes, use nxget -E (see nxget) or the REST API endpoint /v1/objects/{id}/take-screenshot with the sessionName query parameter (see REST API).
The server or host that sends the request must be listed in MasterServers or ControlServers of the agent (see Access Level Matrix).
A request through the server, from the management client or the REST API, also needs the Take screenshot access right on the node (see User Management Reference). The server records these screenshots in the audit log; for the management client, at most once per hour for the same node in one client session.
On Linux, the session agent captures the screen through X11. In a Wayland session it first tries the GNOME Shell screenshot interface, which the session’s policy can refuse, and then falls back to X11.
Framebuffer Screenshots
On Linux systems without a graphical desktop session, such as kiosks, embedded devices, or a server’s text console, the fbdev subagent takes screenshots directly from the framebuffer devices (/dev/fb*).
It does not need the session agent.
At startup, the subagent checks /dev/fb0 to /dev/fb7 and registers each device that the agent process can read.
The session name of a device is its file name: fb0, fb1, and so on (not case-sensitive).
The subagent builds this list only at startup, so restart the agent after you add a framebuffer device or change its permissions.
The screenshot is a PNG image with 8 bits per RGB channel and no alpha channel. It has the framebuffer’s current visible resolution. The subagent supports framebuffers with 32, 24, and 16 bits per pixel; it reads 16-bit framebuffers as RGB565. A request for a framebuffer with another color depth fails.
Enabling Framebuffer Screenshots
-
Install the
netxms-agent-fbdevpackage. -
Make sure that the user the agent runs as can read the framebuffer devices. Run
ls -l /dev/fb*to see the owner and group of each device. -
Load the subagent in
nxagentd.conf:SubAgent = fbdev -
Restart the agent.
-
Check the
Framebuffer.Countmetric (see Framebuffer.Count). It returns the number of framebuffer devices that the subagent registered at startup.
For each registered device, the agent log has the message Registered framebuffer device fb0 (/dev/fb0).
If the subagent finds no readable device, it logs the warning No accessible framebuffer devices found and stays loaded.
The subagent has no configuration parameters.
Taking a Framebuffer Screenshot
The management client cannot request a framebuffer session, because Take screenshot is offered only for Windows nodes. Name the device in the request instead:
-
With
nxget, give the output file and the session name after the agent address:nxget -E 192.168.1.20 screen.png fb0 -
With the REST API, add the session name as a query parameter:
/v1/objects/{id}/take-screenshot?sessionName=fb0. WithoutsessionName, the server requests theConsolesession, which the subagent does not provide.
Troubleshooting
nxget -E shows the agent’s error code and text:
-
919: Session agent not available— the agent has no screenshot source with that session name. Check that the subagent is loaded (Agent.SubAgentList), thatFramebuffer.Countis not 0, and that the session name is correct. -
500: Internal error— the subagent could not open or map the device, or the framebuffer color depth is not supported. Enable thefbdevdebug tag at level 5 to see the cause. -
403: Access denied— the host that sends the request is listed only inServers, not inMasterServersorControlServers.
To see details, enable these agent debug tags with DebugTags in nxagentd.conf (see Diagnostics):
| Debug tag | Component |
|---|---|
|
Agent: |
|
Agent: session agents and registration of screenshot sources (level 3) |
Logs
The session agent writes its log to %LOCALAPPDATA%\nxsagent\nxsagent.log on Windows and to ~/.local/share/nxsagent/nxsagent.log on Linux.
To watch it, stop the session agent running in the user’s session and start it again by hand with nxsagent -f (on Windows, a second copy in the same session exits at once).
For the command-line options, see nxsagent.