sitemanagerd reference

sitemanagerd is the SiteManager service. The Windows and Linux installers start it for you, so you only need this page to change how it runs, or to start it by hand.

Usage

sitemanagerd [options]
sitemanagerd --version
sitemanagerd --state-dir DIR --print-fingerprint
sitemanagerd --state-dir DIR --print-setup-token
sitemanagerd [--listen ADDRESS] [--public-url URL] --print-url

Run sitemanagerd --help for the list of options.

• --version prints the version and exits.
• --print-fingerprint prints the SHA-256 fingerprint of the TLS certificate, and creates the certificate first if it does not exist. Only a service in network mode uses a certificate.
• --print-setup-token prints the first-run setup token. It prints nothing once the first administrator exists. Local mode has no setup token. If the state directory holds neither a setup token nor a user store, the command says so and mentions that local mode needs no setup token.
• --print-url prints the address to open in a browser, using the same rules as the service, and does nothing else. In local mode it is http://127.0.0.1:<port>/. In network mode it is the public URL. The installers use it. Give it the same --listen and --public-url as the service.
• --print-to FILE, together with one of the three options above, writes the value to a new file instead of the screen. The path must be absolute, and the file is created with access for you only.

On Windows, sitemanagerd.exe service install|remove|start|stop manages the Windows service. See SiteManager on Windows.

Options

Where and how it runs

Option	Default	Meaning
--listen ADDRESS	127.0.0.1:8790	The address and port to serve on. The address decides the mode, see Local mode and network mode. Examples: 127.0.0.1:8790 (local mode), :8790 and :8443 (network mode).
--state-dir DIR	The STATE_DIRECTORY environment variable (systemd sets it to /var/lib/sitemanager). On Windows, %ProgramData%\MultiTaction\SiteManager. Otherwise sitemanager-state in the current folder.	Where SiteManager keeps its data.
--public-url URL	https://<computer name>:<port>/	The address that alert messages link back to, in network mode. It must be an https:// address. Local mode refuses this option, and alert messages there link to the loopback address the service listens on, http://127.0.0.1:<port>/ by default.
--log-file PATH	<state-dir>/sitemanagerd.log	Where the service writes its own log. The file must not be one of the other files in the state directory.

Local mode and network mode

The --listen address decides how the service runs. There is no separate switch.

• Local mode is a loopback address: localhost (in any letter case) or a loopback IP address, such as 127.0.0.1:8790, localhost:8790 or [::1]:8790. This is the default. The service serves plain HTTP on that address only, so only this computer can reach it. There are no logins, users, API tokens, setup token or certificate. Every request acts as the administrator /local, and the audit log records that name.
• Network mode is any other address: :8790, 0.0.0.0:8790, a LAN address or a host name. The service serves HTTPS with its own certificate, the first-run setup token, logins, roles and API tokens.

In local mode:

• The Host header of a request must be localhost, 127.0.0.1 or [::1] (or the loopback address --listen names), with the port the service listens on. Anything else gets status 403. This stops a web page from reaching the service through a rebound host name.
• A change (POST, PUT, PATCH or DELETE) whose Origin header is not the service's own http:// address gets 403. A request with no Origin header is allowed.
• --public-url is refused, with the message --public-url names the address other computers use; local mode (a loopback --listen) serves this computer only. Use a network --listen such as :8790.
• The setup, login, Account and Users pages, and the API operations for setup, login, users, tokens, sessions and passwords, are available in network mode only. See The JSON API.
• GET /api/v1/version and GET /api/v1/server report "mode": "local" or "mode": "network". In local mode /api/v1/server has no fingerprint.
• The page footer reads Local mode: this computer only, no logins.
• A --listen whose address turns out not to be a loopback address when the service binds it is refused.

Cornerstone files

Option	Default	Meaning
--cornerstone-user USER	The user running sitemanagerd	Whose home folder holds screen.xml, config.txt and mt-canvus.ini. When the service runs as root on Linux, new files and folders are given to this user. Running as root for another user's home without this option is refused.
--screen-xml PATH	screen.xml in the user's folder	An absolute path that replaces the default.
--config-txt PATH	config.txt in the user's folder	An absolute path that replaces the default.
--canvus-ini PATH	mt-canvus.ini in the user's folder	An absolute path to an mt-canvus.ini that must already exist.
--x-display DISPLAY	:0	The X display used to detect video outputs and to run the blend check (Linux).
--xauthority PATH	.Xauthority in the user's home	The X authority file for that display (Linux).
--scanout-blend PATH	Off	The absolute path of the mt-scanout-blend program. It switches on the Blend check on the Config page.

A path outside the user's home is allowed. SiteManager then checks every folder above it for links. If the user or the paths cannot be used, the service still starts. It generates files and offers them for download, and says why applying them is not available. See Walls and Cornerstone files for the default locations and the rules for writing.

Monitoring and history

Option	Default	Meaning
--poll-idle DURATION	15s	How often a display nobody is looking at is read, from 5 seconds to 5 minutes.
--poll-focused DURATION	2s	How often a display on an open page, in a job or just changed is read, from 1 to 15 seconds.
--history-dir DIR	<state-dir>/history	Where the status history is kept.
--history-max-displays N	128	The most displays the history records, from 1 to 1024. Each takes about 2.6 MB.
--activity-every DURATION	5m	How often the wall's touch traffic is sampled for the idle-wall check. 0 turns it off. Otherwise at least 1 minute.
--drift-every DURATION	15m	How often displays and files are checked for drift. 0 turns it off. Otherwise at least 1 minute.

Durations are written like 30s, 5m or 1h.

The idle-wall check

Option	Default	Meaning
--idle-interval DURATION	5s	The time between two readings.
--idle-samples N	3	How many intervals are measured.
--idle-margin-percent N	50	How far above its own quiet rate a display's traffic may rise and still count as idle, as a percentage. Above 0, at most 1000.
--idle-margin-floor N	20000	The same margin in bytes per second. The larger of the two applies. Above 0, at most 1000000000.
--idle-tolerance N	1000	Used for a display with no baseline yet: how many bytes per second one connection may vary and still count as idle.

See The idle-wall check.

Firmware

Option	Default	Meaning
--firmware-catalogue URL	https://hardware.multitaction.com/firmware/v1/catalogue.json	The firmware catalogue: a signed catalogue address (https, a path ending in .json) or a legacy catalogue base address. With the default, SiteManager falls back to the legacy server when the signed catalogue cannot be fetched.
--firmware-legacy URL	http://update.multitaction.com/taction-firmware/	The legacy update server used when the default signed catalogue cannot be fetched. Empty means no fallback.
--firmware-os OS	linux-tegra+linux-tegra2	The operating system filter of the catalogue.
--firmware-branch BRANCH	stable	The branch of the catalogue to list.

Downloaded and imported images are kept in the firmware folder of the state directory.

Files, folders and logs

The state directory holds everything the service keeps:

Name	What it is
site.json	The site: displays, walls, layouts, rooms, profiles and host settings.
auth.json	Network mode only. Users, API tokens and browser sessions. Passwords and tokens are stored as hashes.
audit.log	The audit log. A new file starts at 10 MiB, and five files are kept.
alerts.json	Alert rules and channels, including the credentials of channels, because the service must send them.
alerts.log	The alert log. 2 MiB per file, with two older files kept.
jobs.json	Jobs, so they survive a restart.
history/	The status history.
firmware/	Cached firmware images.
config-backups/	Backups of the Cornerstone files made before an apply or a restore. The newest 50 are kept.
sitemanagerd.log	The service's own log, as JSON lines. 4 MiB per file, with two older files kept.
tls.crt, tls.key	Network mode only. The service's certificate and its key.
version.key	A random key the service uses to tell when data that holds secrets has changed.
setup-token	Network mode only. The first-run setup token. It exists only until the first administrator is created.

The state directory also holds display-access.json once SiteManager has pinned a display's certificate or secured a display. It holds each display's remembered certificate, its access key and the setting Secure new displays when they are added. It is readable only by the account that runs the service (on Windows, SYSTEM and Administrators). The keys in it are never exported and never appear in the web pages, the JSON API, the command line, the logs, the audit log or the diagnostics bundle. Copy the whole state directory when you back up or move SiteManager: a copy carries the keys, and nothing else does. See Secure your displays.

site.json has a schema number. The current schema is 5. When the service loads an older file, it upgrades it and keeps the original bytes next to it, for example as site.json.v4.bak. It never overwrites such a backup. A SiteManager that is older than the file's schema refuses to load it, instead of dropping fields it does not know. So when more than one SiteManager works on a site, upgrade all of them together.

Local mode does not create or change auth.json, tls.crt, tls.key or setup-token, and never forces setup. If they exist from an earlier network-mode run, they stay as they are, and they are used again when the service next listens on the network.

The state directory holds the credentials of alert channels and, if you use network mode, password hashes and the certificate key. Keep it private. On Linux it is readable by root only, and on Windows by SYSTEM and Administrators only. A profile that holds a secret, for example a proxy password, is stored in site.json, which is readable only by the account that runs the service.

The service writes its log to the file above and to standard error. Under systemd, standard error is the journal (journalctl -u sitemanagerd). On Windows, a failure to start is also written to the Application event log under the source SiteManager. Credentials are never written to the log.

To keep a copy of your site, stop the service and copy the state directory.

Deleting a site

Uninstalling does not delete the state directory. To remove all data, delete it yourself. See the Uninstalling section of your platform: Windows, Linux or macOS.