fix(server): report Windows service start and stop failures to the event log
A service has no console, and a refused data folder or server.json throws before the server's log file exists, so the SCM recorded only error 1064 and the entry to check was lost. ServiceMain and the stop path now also write the reason to the Application event log (source TitanoServer, advapi32 ReportEventW, no message file registered). The Windows README says where to look and that a data folder created by an unelevated console run must be deleted or given to Administrators first. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_012iLMBNwBE2GnphAsu4cjaC
This commit is contained in:
6 files changed
+134
-6
No files matched your search
@@ -116,13 +116,16 @@ Choose the *Server* component in the setup, or unpack `Titano-Server-win-x64-<ve
|
||||
The data folder is readable only by the server's account, SYSTEM and Administrators; without `TITANO_ADMIN_PASSWORD`
|
||||
the first start writes a temporary admin password to `initial-admin-password.txt` there (open it from an
|
||||
administrator prompt). Everything in it must belong to those accounts and nothing in it may be a link: otherwise the
|
||||
server does not start and names the file to check. A new archive folder (default `C:\TitanoArchive`) can be changed
|
||||
only by those accounts and read by other users; when other users can change an existing archive, the log says so.
|
||||
server does not start and names the file to check (in the console, or for the service in Event Viewer › Windows Logs ›
|
||||
Application, source `TitanoServer`). A new archive folder (default `C:\TitanoArchive`) can be changed only by those
|
||||
accounts and read by other users; when other users can change an existing archive, the log says so.
|
||||
|
||||
Run `Titano.Server.exe` in a console, or install it as a Windows service from an administrator prompt with
|
||||
`Titano.Server.exe --install-service` (remove it with `--uninstall-service`). The service runs as LocalSystem, so it
|
||||
registers only from a copy inside `Program Files` that only administrators can change: install for *All users*, or
|
||||
unpack the zip into a folder under `Program Files`.
|
||||
unpack the zip into a folder under `Program Files`. A console run that was not elevated creates the data folder as your
|
||||
own account, and the service then refuses it: delete the folder, or make Administrators its owner, before you start the
|
||||
service.
|
||||
|
||||
## Translations
|
||||
|
||||
|
||||
@@ -86,7 +86,7 @@ Dependencies point one way: `Core` ← `Core.Windows`, `Data`, `Protocol` ← `S
|
||||
| `Server/Api`, `Server/Events` | Endpoint groups (`XxxEndpoints.Map`), API errors, the WebSocket `EventHub` |
|
||||
| `Server/Security` | Accounts, password hashing, tokens, session cookies, login guard, access rules, audit log |
|
||||
| `Server/Storage`, `Server/Jobs` | Archive and processing modules, uploads, render store; `JobEngineHost`, render node service, monitor and availability |
|
||||
| `Server/Hosting`, `Server/Admin/web` | `ServerHost`, certificates, discovery beacon, embedded static files, Windows service; the admin panel (ES modules, one per page) |
|
||||
| `Server/Hosting`, `Server/Admin/web` | `ServerHost`, certificates, discovery beacon, embedded static files, Windows service (start and stop failures in the Application event log); the admin panel (ES modules, one per page) |
|
||||
|
||||
### 2.5 Hosts
|
||||
|
||||
|
||||
@@ -0,0 +1,58 @@
|
||||
using System.Runtime.Versioning;
|
||||
using static Titano.Server.Hosting.Windows.ServiceNative;
|
||||
|
||||
namespace Titano.Server.Hosting.Windows;
|
||||
|
||||
/// <summary>
|
||||
/// Errors of the Windows service in the Application event log (source <c>TitanoServer</c>). A service has no console,
|
||||
/// and a start-up failure comes before the server's log file exists (the data folder that holds it may be the very
|
||||
/// thing refused), so Event Viewer is where an operator finds why the service stopped. The source is not registered
|
||||
/// with a message file: Event Viewer says it found no description for the event, then shows the text whole.
|
||||
/// </summary>
|
||||
internal static unsafe class ServiceEventLog
|
||||
{
|
||||
public const uint StartFailed = 1;
|
||||
public const uint StopFailed = 2;
|
||||
|
||||
/// <summary>ReportEvent takes at most 31,839 characters per string.</summary>
|
||||
public const int MaxLength = 31_839;
|
||||
|
||||
/// <summary>
|
||||
/// The event text: <paramref name="what"/> and the reason the server gave (the entry to check, for a refused data
|
||||
/// folder), then the exception for a bug report; cut to <see cref="MaxLength"/>.
|
||||
/// </summary>
|
||||
public static string Describe(string what, Exception exception)
|
||||
{
|
||||
var text = $"{what} {exception.Message}{Environment.NewLine}{Environment.NewLine}{exception}";
|
||||
if (text.Length <= MaxLength) return text;
|
||||
var cut = MaxLength - 1;
|
||||
// Never half a surrogate pair.
|
||||
if (char.IsHighSurrogate(text[cut - 1])) cut--;
|
||||
return string.Concat(text.AsSpan(0, cut), "…");
|
||||
}
|
||||
|
||||
/// <summary>Writes an error event; false when the event log could not be written (the console still gets it).</summary>
|
||||
[SupportedOSPlatform("windows")]
|
||||
public static bool Error(uint eventId, string text) => Error(WindowsServiceHost.ServiceName, eventId, text);
|
||||
|
||||
/// <summary><see cref="Error(uint, string)"/> as <paramref name="sourceName"/> (tests write as their own source).</summary>
|
||||
[SupportedOSPlatform("windows")]
|
||||
internal static bool Error(string sourceName, uint eventId, string text)
|
||||
{
|
||||
var source = RegisterEventSourceW(null, sourceName);
|
||||
if (source == 0) return false;
|
||||
try
|
||||
{
|
||||
fixed (char* chars = text.Length <= MaxLength ? text : text[..MaxLength])
|
||||
{
|
||||
var strings = stackalloc char*[1];
|
||||
strings[0] = chars;
|
||||
return ReportEventW(source, EventLogErrorType, 0, eventId, 0, 1, 0, strings, null);
|
||||
}
|
||||
}
|
||||
finally
|
||||
{
|
||||
DeregisterEventSource(source);
|
||||
}
|
||||
}
|
||||
}
|
||||
@@ -3,7 +3,7 @@ using System.Runtime.Versioning;
|
||||
|
||||
namespace Titano.Server.Hosting.Windows;
|
||||
|
||||
/// <summary>Service Control Manager functions of advapi32 (no Windows-only package needed).</summary>
|
||||
/// <summary>Service Control Manager and event log functions of advapi32 (no Windows-only package needed).</summary>
|
||||
[SupportedOSPlatform("windows")]
|
||||
internal static unsafe partial class ServiceNative
|
||||
{
|
||||
@@ -29,6 +29,8 @@ internal static unsafe partial class ServiceNative
|
||||
public const uint ErrorCallNotImplemented = 120;
|
||||
public const uint ErrorExceptionInService = 1064;
|
||||
|
||||
public const ushort EventLogErrorType = 0x1;
|
||||
|
||||
[StructLayout(LayoutKind.Sequential)]
|
||||
public struct ServiceStatus
|
||||
{
|
||||
@@ -90,4 +92,16 @@ internal static unsafe partial class ServiceNative
|
||||
[LibraryImport("advapi32.dll", SetLastError = true)]
|
||||
[return: MarshalAs(UnmanagedType.Bool)]
|
||||
public static partial bool CloseServiceHandle(nint handle);
|
||||
|
||||
[LibraryImport("advapi32.dll", SetLastError = true, StringMarshalling = StringMarshalling.Utf16)]
|
||||
public static partial nint RegisterEventSourceW(string? uncServerName, string sourceName);
|
||||
|
||||
[LibraryImport("advapi32.dll", SetLastError = true)]
|
||||
[return: MarshalAs(UnmanagedType.Bool)]
|
||||
public static partial bool ReportEventW(nint eventLog, ushort type, ushort category, uint eventId, nint userSid, ushort stringCount, uint dataSize,
|
||||
char** strings, void* rawData);
|
||||
|
||||
[LibraryImport("advapi32.dll", SetLastError = true)]
|
||||
[return: MarshalAs(UnmanagedType.Bool)]
|
||||
public static partial bool DeregisterEventSource(nint eventLog);
|
||||
}
|
||||
@@ -9,7 +9,8 @@ namespace Titano.Server.Hosting.Windows;
|
||||
/// <summary>
|
||||
/// Runs the server as a Windows service with the SCM API directly (StartServiceCtrlDispatcherW,
|
||||
/// RegisterServiceCtrlHandlerExW, SetServiceStatus). Stop and shutdown requests stop the web host gracefully: running
|
||||
/// jobs keep their checkpoints and resume at the next start.
|
||||
/// jobs keep their checkpoints and resume at the next start. A failure to start or stop goes to the Application event
|
||||
/// log (<see cref="ServiceEventLog"/>), since a service has no console.
|
||||
/// </summary>
|
||||
[SupportedOSPlatform("windows")]
|
||||
public static class WindowsServiceHost
|
||||
@@ -56,7 +57,9 @@ public static class WindowsServiceHost
|
||||
}
|
||||
catch (Exception ex)
|
||||
{
|
||||
// A refused data folder or server.json says which entry to check; the SCM itself records only error 1064.
|
||||
Console.Error.WriteLine(ex);
|
||||
ServiceEventLog.Error(ServiceEventLog.StartFailed, ServiceEventLog.Describe("Titano Server did not start:", ex));
|
||||
Report(Status.Stopped(ErrorExceptionInService));
|
||||
}
|
||||
}
|
||||
@@ -96,6 +99,7 @@ public static class WindowsServiceHost
|
||||
catch (Exception ex)
|
||||
{
|
||||
Console.Error.WriteLine(ex);
|
||||
ServiceEventLog.Error(ServiceEventLog.StopFailed, ServiceEventLog.Describe("Titano Server did not stop cleanly:", ex));
|
||||
exitCode = ErrorExceptionInService;
|
||||
}
|
||||
Report(Status.Stopped(exitCode));
|
||||
|
||||
@@ -1,3 +1,4 @@
|
||||
using System.Diagnostics.Eventing.Reader;
|
||||
using System.Security.AccessControl;
|
||||
using System.Security.Principal;
|
||||
using Titano.Server.Hosting;
|
||||
@@ -41,6 +42,54 @@ public sealed class WindowsServiceTests(TestContext context)
|
||||
Assert.Equal(1064u, new ServiceStatusTracker().Stopped(1064).ExitCode);
|
||||
}
|
||||
|
||||
[Test]
|
||||
public void AServiceFailureLeadsWithTheReasonTheServerGave()
|
||||
{
|
||||
var refused = new InvalidOperationException(@"C:\ProgramData\Titano Server belongs to PC\ada, not to SYSTEM, Administrators or the account Titano Server runs as.");
|
||||
var text = ServiceEventLog.Describe("Titano Server did not start:", refused);
|
||||
Assert.True(text.StartsWith(@"Titano Server did not start: C:\ProgramData\Titano Server belongs to PC\ada", StringComparison.Ordinal), text);
|
||||
Assert.Contains("System.InvalidOperationException", text);
|
||||
|
||||
// ReportEvent refuses a longer string: the text is cut, never between the halves of a surrogate pair.
|
||||
var cut = ServiceEventLog.Describe("x", new InvalidOperationException(new string('a', ServiceEventLog.MaxLength)));
|
||||
Assert.Equal(ServiceEventLog.MaxLength, cut.Length);
|
||||
Assert.True(cut.EndsWith("a\u2026", StringComparison.Ordinal), cut[^5..]);
|
||||
var pair = ServiceEventLog.Describe("x", new InvalidOperationException(new string('a', ServiceEventLog.MaxLength - 4) + "\uD83D\uDE00" + new string('b', 99)));
|
||||
Assert.Equal(ServiceEventLog.MaxLength - 1, pair.Length);
|
||||
Assert.True(pair.EndsWith("a\u2026", StringComparison.Ordinal), pair[^5..]);
|
||||
}
|
||||
|
||||
[Test]
|
||||
[WindowsOnly]
|
||||
public void AServiceFailureReachesTheApplicationEventLog()
|
||||
{
|
||||
if (!OperatingSystem.IsWindows()) return;
|
||||
// Written as a source of its own, so a test run never looks like a failed service in Event Viewer.
|
||||
const string source = "Titano.Server.Tests";
|
||||
var marker = source + " " + Guid.NewGuid().ToString("N");
|
||||
Assert.True(ServiceEventLog.Error(source, ServiceEventLog.StartFailed, marker), "the Application log takes the event");
|
||||
var filter = $"*[System[Provider[@Name='{source}'] and EventID={ServiceEventLog.StartFailed}]]";
|
||||
var query = new EventLogQuery("Application", PathType.LogName, filter) { ReverseDirection = true };
|
||||
for (var attempt = 0; attempt < 50; attempt++)
|
||||
{
|
||||
using (var reader = new EventLogReader(query))
|
||||
{
|
||||
for (var read = 0; read < 100 && reader.ReadEvent() is { } record; read++)
|
||||
{
|
||||
using (record)
|
||||
{
|
||||
// The event's one string, which Event Viewer shows whole.
|
||||
if (record.Properties.Count != 1 || record.Properties[0].Value as string != marker) continue;
|
||||
Assert.Equal((byte?)2, record.Level, "an error");
|
||||
return;
|
||||
}
|
||||
}
|
||||
}
|
||||
Thread.Sleep(100);
|
||||
}
|
||||
Assert.Fail($"No {source} event carries '{marker}'.");
|
||||
}
|
||||
|
||||
[Test]
|
||||
[WindowsOnly]
|
||||
public void TheServiceIsRegisteredOnlyFromInsideProgramFiles()
|
||||
|
||||
Reference in new issue
Block a user