The curiosity Windows service

Reference for the curiosity service that Install creates: what the setup script checks and applies, how the service is defined, and what the start error codes mean. Nothing on this page is a step you need to take after a successful install.

What configure-windows-service.ps1 does

The script ships in the install folder and is written for PowerShell 5.1 or later: it refuses to run without elevation, and it must sit next to curiosity.exe. Started from a Command Prompt — that is, through powershell.exe -File … — it prints a warning and carries on, because cmd.exe has parsed that command line first and rewrites quotes, %VAR% references, ^ escapes and the $ of a gMSA name. It never supplies a configuration value on its own. Run without an argument it prints its command list and does nothing else — that and help are the only forms that run without elevation and without curiosity.exe beside them.

Without arguments

It checks, then creates or updates the service:

1. Environment variables. Every MSK_* variable visible in the console or in the machine-scope registry key is checked. A name the server does not read is reported as a probable typo; a variable that exists only in this session or for the current user is reported as invisible to the service, with the [Environment]::SetEnvironmentVariable(…, "Machine") line that fixes it; a machine-scope variable set after the session was opened is reported as not visible here yet.
2. Folders. The install folder, MSK_GRAPH_STORAGE, MSK_LOG_PATH, MSK_AUDIT_LOG_PATH, MSK_GRAPH_TEMP_FOLDER, the served front-end folder (MSK_WWW_FOLDER, or wwwroot inside the install folder when it is not set) and the optional journal, backup, fonts, plugins and Git-tracking folders, read from machine scope the way the service sees them. A missing folder other than the install folder is created as administrator. Each folder is checked for a UNC or mapped-drive path (a service has no drive mappings, and LocalSystem reaches a share as the computer account), a location inside C:\Users, whether it is writable at all, whether SYSTEM holds full control or modify (when the service runs as LocalSystem), and whether its drive has less than 10 GB free. A missing MSK_GRAPH_STORAGE is a warning that names the per-account default it falls back to.
3. The service. A new curiosity service is created with the command line below, running as LocalSystem, and started with Start-Service. An existing service is stopped, its command line, display name and start type are rewritten through Win32_Service, and it is started again — its logon account and password are kept. If the start fails, the script prints the Windows error and a short explanation of 1053 and 1069.

Warnings are counted and printed but never stop the script — it says so and creates the service anyway, and being started from a Command Prompt is a warning like any other. Only three things stop it: a non-Windows host, no elevation, and no curiosity.exe beside it. The access of an account other than LocalSystem is not checked in this mode. An install path containing parentheses (C:\Program Files (x86)\…) is handled correctly.

setup

.\configure-windows-service.ps1 setup is the guided mode. It asks three things — the data folder, from which the five MSK_* paths are derived; whether to seed the admin account through MSK_ADMIN_USER, MSK_ADMIN_EMAIL and MSK_ADMIN_PASSWORD; and whether the service runs as LocalSystem, a user account or a gMSA — proposing whatever is already configured as the default.

The data folder is proposed beside the install folder — E:\CuriosityData for an install in E:\Curiosity — and the paths derived from it are Storage, Logs, Logs\Audit, Temp and www (MSK_GRAPH_STORAGE, MSK_LOG_PATH, MSK_AUDIT_LOG_PATH, MSK_GRAPH_TEMP_FOLDER, MSK_WWW_FOLDER). A folder inside the install folder is refused, because that is what keeps the install folder read-only for the service account. An install whose four path variables are already set is offered them unchanged instead, and its MSK_WWW_FOLDER is then left as it is — a workspace that has published its own front-end serves it from that folder.

It then prints a plan in which every item is [done] or [todo]. The status comes from looking at the registry, the folders, the ACLs, the local security policy and the service definition; nothing is remembered between runs. After you confirm, the [todo] items are applied:

• [Environment]::SetEnvironmentVariable at machine scope for each variable whose value differs;
• the data, log, audit, temp and front-end folders, followed by the same folder checks as in configure below;
• for an account other than LocalSystem: icacls grants — read and execute on the install folder, full control on data and temp, modify on logs and on the served front-end folder, inheritable and applied to existing files — and the Log on as a service right through secedit, with the account resolved to its SID first. A gMSA is also checked with Test-ADServiceAccount when the Active Directory PowerShell module is installed;
• the service: created, or updated in place with the new account and command line, then started.

Running setup again is safe: it reports everything as [done] and only restarts the service.

configure

.\configure-windows-service.ps1 configure does the same work without the questions — check and install name the same thing. It checks, then creates or updates the service:

1. Environment variables. Every MSK_* variable visible in the console or in the machine-scope registry key is checked. A name the server does not read is reported as a probable typo; a variable that exists only in this session or for the current user is reported as invisible to the service, with the [Environment]::SetEnvironmentVariable(…, "Machine") line that fixes it; a machine-scope variable set after the session was opened is reported as not visible here yet.
2. Folders. The install folder, MSK_GRAPH_STORAGE, MSK_LOG_PATH, MSK_AUDIT_LOG_PATH, MSK_GRAPH_TEMP_FOLDER and the optional journal, backup, web-root, fonts, plugins and Git-tracking folders, read from machine scope the way the service sees them. A missing folder other than the install folder is created as administrator. Each folder is checked for a UNC or mapped-drive path (a service has no drive mappings, and LocalSystem reaches a share as the computer account), a location inside C:\Users, whether it is writable at all, whether SYSTEM holds full control or modify (when the service runs as LocalSystem), and whether its drive has less than 10 GB free. A missing MSK_GRAPH_STORAGE is a warning that names the per-account default it falls back to.
3. The service. A new curiosity service is created with the command line below, running as LocalSystem, and started with Start-Service. An existing service is stopped, its command line, display name and start type are rewritten through Win32_Service, and it is started again — its logon account and password are kept. If the start fails, the script prints the Windows error and a short explanation of 1053 and 1069.

Warnings are counted and printed but never stop the script — it says so and creates the service anyway, and being started from a Command Prompt is a warning like any other. Only three things stop it: a non-Windows host, no elevation, and no curiosity.exe beside it. The access of an account other than LocalSystem is not checked in this mode. An install path containing parentheses (C:\Program Files (x86)\…) is handled correctly.

start, stop and uninstall

These three act on a service that already exists and configure nothing; each reports what the service is and refuses, with exit code 1, when there is none. They do not need curiosity.exe beside the script, but they do need elevation.

• start starts the service and prints its status and logon account. On a failure it prints the Windows error and the same explanation of 1053 and 1069 as the modes above. A service that is already running is reported and left alone.
• stop stops the service. Its start type stays Automatic, so it starts again on the next boot — this is not how you disable it. A workspace with a large graph can take a while to shut down cleanly; a timeout is reported and the command exits 1.
• uninstall stops the service and deletes its definition through Win32_Service. It prints the service and its command line, states what is being removed, and asks to confirm — -Yes answers that question for an unattended removal. The workspace data, the logs, the MSK_* machine-scope variables and the installed files are left exactly as they are, so setup afterwards recreates the service over the same workspace. A services.msc window left open still lists the service until it is closed.

The service command line

The service is created with this command line — every path and password comes from the machine-scope environment:

curiosity.exe --MSK_RUN_AS_SERVICE=true

• --MSK_RUN_AS_SERVICE=true must be part of the binPath command line — the script passes it there rather than as a machine-wide variable. It registers the process with the Service Control Manager (without it, sc start fails with error 1053 after 30 seconds, because the exe runs as a console app the SCM never hears from), sets the working directory to the install folder (services otherwise start in System32), and keeps the terminal interface off, which a service has no console for. The server reads it from the machine-scope environment as well, so setting MSK_RUN_AS_SERVICE there fixes the working directory for a service somebody created without the flag — but the command line is what the script writes, and what a hand-made service should carry.
• When MSK_LOG_PATH is not set at machine scope, the script also appends --MSK_LOG_PATH="<install folder>\logs" so the logs land next to the binaries instead of in the service account's temp folder. That override writes inside the install folder: set MSK_LOG_PATH at machine scope and re-run the script to remove it (the account is kept), which is one of the two settings a read-only install folder needs.

To create the same service without the script, from an elevated Command Prompt (sc.exe is easiest to quote there):

sc create curiosity binPath= "E:\Curiosity\curiosity.exe --MSK_RUN_AS_SERVICE=true" displayname= "Curiosity Workspace" start= auto
sc start  curiosity
sc query  curiosity

sc does not grant Log on as a service — for an account other than LocalSystem, grant it as described on Service account. The service is also visible in services.msc.

Service start errors

When the service fails to start, the script prints the Windows error code Start-Service reported; it explains 1053 and 1069 briefly, the table below covers the rest. A failure inside the workspace itself is written to error.log — in the log folder, next to curiosity.exe, or in the service account's temp folder — and to the Application event log as a .NET Runtime entry.

Binaries or data under another user's C:\Users\<name> profile is the most common cause of 1053 and 5 — see Directory layout. For a gMSA, gMSA troubleshooting covers the account-side causes.

See also

• Install — the install steps.
• Service account — running the service as a dedicated user or a gMSA.
• Configuration reference — every MSK_* variable.
• Troubleshooting.