Magic Suite Agent

What is the Magic Suite Agent?

The Magic Suite Agent is a lightweight service that runs on your servers to enable Magic Suite to interact with your infrastructure. It provides capabilities including:

• SNMP monitoring – discover and poll network devices
• SQL queries – execute queries against local databases via Agent.Sql macros
• Web queries – make HTTP requests from within your network via Agent.WebQuery macros
• Syslog collection – receive and forward syslog messages
• NetFlow collection – receive and forward NetFlow data
• PowerShell execution – run PowerShell scripts on the host

The agent connects outbound to your Magic Suite instance – no inbound firewall rules are required.

Downloading the Agent

Agent installers are available for Windows, Linux, and macOS. Download the installer for your platform from the links below:

Platform	Download	Format
Windows	Download Windows Installer	MSI (recommended)
Linux	Download Linux Binary	Self-contained executable
macOS	Download macOS Binary	Self-contained executable

Note: Each Magic Suite environment serves its own agent version. If you are using a non-production environment (e.g. beta, test), download the agent from the corresponding environment URL, for example https://www.beta.magicsuite.net/agent/windows.

Installing on Windows

The Windows agent is distributed as an MSI installer that handles everything automatically.

New Installation

1. Download MagicSuiteAgent.msi from the link above.
2. Run the installer (double-click or msiexec /i MagicSuiteAgent.msi).
3. The installer will:
   • Install the agent to C:\Program Files\Magic Suite Agent\
   • Create an example configuration file (appsettings.example.json)
   • Register the MagicSuiteAgent Windows service (auto-start, runs as LocalSystem)
   • Configure service failure recovery (automatic restart)
   • Start the service
4. Edit C:\Program Files\Magic Suite Agent\appsettings.json to configure the agent (see Configuration below).
5. Restart the service: sc stop MagicSuiteAgent && sc start MagicSuiteAgent

Upgrading on Windows

Simply download and run the latest MSI. The installer uses Windows Installer MajorUpgrade – it will:

1. Stop the running service
2. Remove the previous version
3. Install the new version
4. Preserve your existing appsettings.json and appsettings.Local.json
5. Restart the service

Your configuration is preserved across upgrades. No manual steps are needed.

Migrating from a Legacy Agent

If you are upgrading from an older agent version (e.g. “Magic Suite Agent 3”, “Magic Suite Agent 2”, or “MagicSuite Agent”), the MSI installer will automatically:

• Stop and remove legacy services
• Copy your existing configuration from the old install location

No manual migration is required.

Silent Installation

For automated deployments, the MSI supports silent installation:

msiexec /i MagicSuiteAgent.msi /quiet /norestart

Uninstalling on Windows

Use Add or Remove Programs in Windows Settings, or run:

msiexec /x MagicSuiteAgent.msi /quiet

The service will be stopped and removed automatically.

Installing on Linux

New Installation

1. Download the Linux binary:

   curl -o MagicSuite.Agent https://www.magicsuite.net/agent/linux
   chmod +x MagicSuite.Agent

2. Move it to the install location:

   sudo mkdir -p /opt/magicsuite-agent
   sudo mv MagicSuite.Agent /opt/magicsuite-agent/

3. Create the configuration file (see Configuration below):

   sudo nano /opt/magicsuite-agent/appsettings.json

4. Create a systemd service file:

   sudo tee /etc/systemd/system/magicsuite-agent.service > /dev/null <<EOF
   [Unit]
   Description=Magic Suite Agent
   After=network.target
   
   [Service]
   Type=notify
   ExecStart=/opt/magicsuite-agent/MagicSuite.Agent
   WorkingDirectory=/opt/magicsuite-agent
   Restart=always
   RestartSec=10
   User=root
   
   [Install]
   WantedBy=multi-user.target
   EOF

5. Enable and start the service:

   sudo systemctl daemon-reload
   sudo systemctl enable magicsuite-agent
   sudo systemctl start magicsuite-agent

Upgrading on Linux

1. Stop the service: sudo systemctl stop magicsuite-agent
2. Download the new binary:

   sudo curl -o /opt/magicsuite-agent/MagicSuite.Agent https://www.magicsuite.net/agent/linux
   sudo chmod +x /opt/magicsuite-agent/MagicSuite.Agent

3. Start the service: sudo systemctl start magicsuite-agent

Your configuration files are not overwritten.

Checking Status on Linux

sudo systemctl status magicsuite-agent
sudo journalctl -u magicsuite-agent -f

Installing on macOS

New Installation

1. Download the macOS binary:

   curl -o MagicSuite.Agent https://www.magicsuite.net/agent/macos
   chmod +x MagicSuite.Agent

2. Move it to the install location:

   sudo mkdir -p /opt/magicsuite-agent
   sudo mv MagicSuite.Agent /opt/magicsuite-agent/

3. Create the configuration file (see Configuration below):

   sudo nano /opt/magicsuite-agent/appsettings.json

4. Create a launchd plist:

   sudo tee /Library/LaunchDaemons/com.panoramicdata.magicsuite-agent.plist > /dev/null <<EOF
   <?xml version="1.0" encoding="UTF-8"?>
   <!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
   <plist version="1.0">
   <dict>
   	<key>Label</key>
   	<string>com.panoramicdata.magicsuite-agent</string>
   	<key>ProgramArguments</key>
   	<array>
   		<string>/opt/magicsuite-agent/MagicSuite.Agent</string>
   	</array>
   	<key>WorkingDirectory</key>
   	<string>/opt/magicsuite-agent</string>
   	<key>RunAtLoad</key>
   	<true/>
   	<key>KeepAlive</key>
   	<true/>
   </dict>
   </plist>
   EOF

5. Load and start the service:

   sudo launchctl load /Library/LaunchDaemons/com.panoramicdata.magicsuite-agent.plist

Upgrading on macOS

1. Unload the service: sudo launchctl unload /Library/LaunchDaemons/com.panoramicdata.magicsuite-agent.plist
2. Download the new binary:

   sudo curl -o /opt/magicsuite-agent/MagicSuite.Agent https://www.magicsuite.net/agent/macos
   sudo chmod +x /opt/magicsuite-agent/MagicSuite.Agent

3. Reload the service: sudo launchctl load /Library/LaunchDaemons/com.panoramicdata.magicsuite-agent.plist

Configuration

The agent is configured via appsettings.json. You can also use appsettings.Local.json for environment-specific overrides (this file takes precedence and is preserved across upgrades).

Minimum Required Configuration

At minimum, you need to configure the agent to connect to your Magic Suite instance:

{
  "Agents": [
	{
	  "ApiUrl": "https://api.magicsuite.net/",
	  "ApiTokenName": "your-token-name",
	  "ApiTokenKey": "your-token-key",
	  "ConnectionId": 123
	}
  ]
}

Where:

• ApiUrl – The URL of your Magic Suite API (e.g. https://api.magicsuite.net/ for production)
• ApiTokenName and ApiTokenKey – An API token created in the Magic Suite Admin App under API Tokens
• ConnectionId – The ID of the Agent Connection configured in the Admin App under Connections

Full Configuration Reference

Setting	Type	Default	Description
DiscoveryLoopDelayMs	int	10	Delay in milliseconds between discovery polling loops
StartUpDelaySeconds	int	10	Delay in seconds before the agent starts processing after service start
Agents[].ApiUrl	string	–	Magic Suite API endpoint URL
Agents[].ApiTokenName	string	–	API token name
Agents[].ApiTokenKey	string	–	API token key
Agents[].ConnectionId	int	–	Agent Connection ID from Admin App
Agents[].MaxConcurrentRequests	int	5	Maximum concurrent requests (capped at CPU core count)

Optional Feature Configuration

The agent supports additional features that can be enabled per-agent:

MonitorMagic (SNMP Monitoring)

"MonitorMagic": {
  "Properties": {
	"subnets": {
	  "Type": "List<string>",
	  "Value": "[ \"10.0.0.0/24\" ]",
	  "Description": "Subnets to scan for devices"
	}
  }
}

Syslog Collection

"Syslog": {
  "LocalAddress": "Any",
  "UdpPort": 514
}

NetFlow Collection

"NetFlow": {
  "LocalAddress": "Any",
  "UdpPort": 2055
}

Logging Configuration

Logging is configured via Serilog in the Serilog section of appsettings.json. The default configuration writes to the console and to rolling log files:

"Serilog": {
  "MinimumLevel": {
	"Default": "Information",
	"Override": {
	  "Microsoft": "Warning",
	  "System": "Warning"
	}
  },
  "WriteTo": [
	{
	  "Name": "Console"
	},
	{
	  "Name": "File",
	  "Args": {
		"path": "Logs/MagicSuiteAgent.log",
		"rollingInterval": "Day"
	  }
	}
  ]
}

Setting Up an Agent Connection

Before the agent can communicate with Magic Suite, you need to create an Agent Connection in the Admin App:

1. In the Admin App, go to Connections.
2. Click Create.
3. Set the Type to Agent.
4. Give it a descriptive Name (e.g. “London Office Agent”).
5. Leave the URL and credentials fields blank (the agent connects outbound).
6. Click Save and note the Connection ID shown.
7. Use this Connection ID in your agent’s appsettings.json.

Verifying the Agent

Once configured and running, you can verify the agent is connected:

• In the Admin App, go to Connections and check the status of your Agent Connection.
• A connected agent will show a green status indicator.
• Check the agent logs for any connection errors.

Troubleshooting

Issue	Solution
Agent service won’t start	Check that appsettings.json exists and is valid JSON. Check the Windows Event Log or systemd journal for errors.
Agent can’t connect to API	Verify the ApiUrl is reachable from the agent host. Check firewall rules allow outbound HTTPS (port 443).
Authentication errors	Verify your ApiTokenName and ApiTokenKey are correct and the token has not expired.
Connection ID not found	Ensure the ConnectionId matches an existing Agent Connection in the Admin App.
SNMP discovery not working	Check that the subnet configuration is correct and SNMP (UDP 161) is reachable from the agent host.