Solace Service 10.3-solace.2 help (Windows x64)

What is in the ZIP

It is a self-contained build: no .NET install is needed.

Install

1. Check the download: in PowerShell run Get-FileHash .\Solace-Service-10.3-solace.2-Windows-x64-unsigned.zip and compare the SHA-256 with the one on the product page.
2. Unzip to a folder that will stay put, for example C:\Tools\SolaceService. Services keep running from files Solace Service places in %ProgramData%\SolaceService, so you can move the ZIP folder later, but keep the apps somewhere permanent.
3. The apps are not code-signed yet. If Windows SmartScreen says "Windows protected your PC", click More info, then Run anyway.
4. Installing, starting and stopping services needs administrator rights. The apps ask for elevation (UAC) when they start; for the CLI, open an elevated terminal (Run as administrator). Without administrator rights the CLI only runs --help, --version and status; every other command stops with exit code 5 before it creates or changes anything.

First run: what gets created

• %ProgramData%\SolaceService\ holds the service database (db\SolaceService.db), the encryption key for stored passwords (security\), the helper programs that Windows runs for each service (SolaceService.Service.exe, SolaceService.Restarter.exe, SolaceService.Host.exe) and logs (logs\). Only Administrators and SYSTEM can change it. Solace Service creates this folder only from an elevated process. If a standard user created or changed it (10.3-solace.1 could do that when its command-line tool was run without administrator rights), the next elevated app or CLI run, or the helper service when it starts, resets the owner to Administrators and removes the extra permissions.
• The first time you install a service, Solace Service also installs one small helper service, Solace Service Host (SolaceServiceHost). It hands each of your services its own settings over a local named pipe, so service accounts never read the database. Leave it running while you use Solace Service.
• Nothing is sent over the network. There is no update check and no telemetry. (A service's optional heartbeat URL, if you set one, is the only outbound request, and only to the address you type.)

Install a service with the desktop app

1. Run SolaceService.exe.
2. Service name: a short name with no spaces is easiest (for example MyApi). Display name and Description are what you see in services.msc.
3. Process path: the program to run (for example C:\Program Files\nodejs\node.exe). Startup directory and Process parameters are its working folder and arguments (for example server.js --port 8080).
4. Optional tabs: startup type, process priority, CPU affinity, stdout/stderr log files with rotation, health monitoring and recovery, environment variables, dependencies, the log-on account, and pre-launch / post-launch / pre-stop / post-stop hooks.
5. Click Install. Then start it from the app, from the Manager, or from services.msc.

Manage services

Run SolaceService.Manager.exe to see every service installed with Solace Service, with status, CPU and memory. From there you can start, stop, restart, configure, export, uninstall and read each service's console and performance history.

Command line

Run from an elevated terminal in the folder where you unzipped the files.

solace-service-cli.exe help
solace-service-cli.exe install --name MyApi --path "C:\Program Files\nodejs\node.exe" --startupDir "C:\apps\api" --params "server.js --port 8080" --stdout "C:\apps\api\logs\out.log" --stderr "C:\apps\api\logs\err.log"
solace-service-cli.exe start --name MyApi
solace-service-cli.exe status --name MyApi
solace-service-cli.exe show --name MyApi
solace-service-cli.exe stop --name MyApi
solace-service-cli.exe restart --name MyApi
solace-service-cli.exe uninstall --name MyApi
solace-service-cli.exe export --name MyApi --config json --path C:\backup\MyApi.json
solace-service-cli.exe import --config json --path C:\backup\MyApi.json --install

solace-service-cli.exe <command> --help lists every option of a command. When the program's own arguments start with a dash, attach them with = so the CLI does not read them as its own options: --params="-t 127.0.0.1".

A quick test service that pings localhost forever:

solace-service-cli.exe install --name PingTest --path C:\Windows\System32\PING.EXE --params="-t 127.0.0.1"
solace-service-cli.exe start --name PingTest
solace-service-cli.exe status --name PingTest
solace-service-cli.exe stop --name PingTest
solace-service-cli.exe uninstall --name PingTest

The most used install options:

Secrets: instead of putting a password or sensitive parameters on the command line (where they can show up in process listings and shell history), set them in an environment variable for the CLI process: SOLACE_SERVICE_PASSWORD, SOLACE_SERVICE_PROCESS_PARAMETERS, SOLACE_SERVICE_ENVIRONMENT_VARIABLES, SOLACE_SERVICE_FAILURE_PROGRAM_PARAMETERS, SOLACE_SERVICE_PRE_LAUNCH_PARAMETERS, SOLACE_SERVICE_PRE_LAUNCH_ENVIRONMENT_VARIABLES, SOLACE_SERVICE_POST_LAUNCH_PARAMETERS, SOLACE_SERVICE_PRE_STOP_PARAMETERS, SOLACE_SERVICE_POST_STOP_PARAMETERS. Passwords and parameters are stored encrypted (AES, key protected by Windows DPAPI).

PowerShell module

Import-Module .\SolaceService.psd1
Install-SolaceService -Name MyApi -Path "C:\Program Files\nodejs\node.exe" -StartupDir "C:\apps\api" -Params "server.js"
Start-SolaceService -Name MyApi
Get-SolaceServiceStatus -Name MyApi
Stop-SolaceService -Name MyApi
Uninstall-SolaceService -Name MyApi

Other commands: Restart-SolaceService, Show-SolaceService, Show-SolaceServices, Export-SolaceServiceConfig, Import-SolaceServiceConfig, Get-SolaceServiceVersion, Get-SolaceServiceHelp, Set-SolaceServiceConfig, Set-SolaceServiceHardenedFileAcl. The module looks for solace-service-cli.exe next to itself first. More examples are in solace-service-module-examples.ps1.

Protected variables

Some environment variables are protected so a service's settings cannot hijack the process or Windows itself.

• Always protected (cannot be set per service): system and identity variables such as PATH, SYSTEMROOT, WINDIR, TEMP, TMP, COMSPEC, USERPROFILE, PROGRAMDATA, and loader or profiler hooks such as COR_PROFILER, DOTNET_STARTUP_HOOKS and LD_PRELOAD.
• Protected by default (allowed when you tick Allow overriding runtime variables, or pass --allowOverriddenRuntimeVars): runtime settings such as JAVA_HOME, JAVA_OPTS, CATALINA_OPTS, NODE_OPTIONS, PYTHONPATH, HTTP_PROXY and SSL_CERT_FILE.

If a variable you set is ignored, it is on one of these lists; the service log says which.

Files in use when updating

When Solace Service updates its helper programs in %ProgramData%\SolaceService and a file is locked, it asks Windows (Restart Manager) which processes hold it and stops only those, never protected system processes. If Windows cannot tell, the update stops and the log says which file is locked; stop the service that uses it and try again.

Logs

• App, Manager and CLI logs: %ProgramData%\SolaceService\logs\. A CLI run without administrator rights (for example --help or status before anything is installed) logs to %LOCALAPPDATA%\SolaceService\logs\ instead.
• Each service: the stdout/stderr files you chose, plus the Windows Event Log (Application log, source "Solace Service").

Uninstall

1. Uninstall each service (Manager, solace-service-cli.exe uninstall --name <name>, or Uninstall-SolaceService).
2. In an elevated terminal remove the helper service: sc.exe stop SolaceServiceHost then sc.exe delete SolaceServiceHost.
3. Delete %ProgramData%\SolaceService and the folder you unzipped.

Support

Email solacesoftware@smilingface.cloud with the version (Help > About) and the relevant log lines from %ProgramData%\SolaceService\logs\.