This is the documentation for the development version. There are no official binaries for it; build it from the source code in git. Download links on these pages work only after the release. For the current release, see version 7.0.

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-session package. It installs /usr/bin/nxsagent and 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 sessionagent for /MERGETASKS, see Windows Agent Installer Reference). The installer adds nxsagent.exe -H to 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 of WAYLAND_DISPLAY when DISPLAY is not set, or Console when neither is set; Agent.SessionAgents shows it.

  • On Linux with the fbdev subagent, the session names fb0 to fb7 select a framebuffer device; see Framebuffer Screenshots.

The management client offers Take screenshot for Windows and Linux nodes with an agent; it captures the Console session, or the first connected session agent if there is no Console session. For other sessions and for framebuffer devices, 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

  1. Install the netxms-agent-fbdev package.

  2. 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.

  3. Load the subagent in nxagentd.conf:

    SubAgent = fbdev
  4. Restart the agent.

  5. Check the Framebuffer.Count metric (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 it selects only among the connected session agents (Agent.SessionAgents); without one, it reports that no session is active. 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. Without sessionName, the server requests the Console session, 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), that Framebuffer.Count is 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 the fbdev debug tag at level 5 to see the cause.

  • 403: Access denied — the host that sends the request is listed only in Servers, not in MasterServers or ControlServers.

To see details, enable these agent debug tags with DebugTags in nxagentd.conf (see Diagnostics):

Debug tag Component

fbdev

Agent: fbdev subagent: device access, resolution and color depth (levels 3 to 5)

sa

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.