Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
12 changes: 11 additions & 1 deletion Program.cs
Original file line number Diff line number Diff line change
Expand Up @@ -262,8 +262,18 @@ static int Main(string[] args)
silentMode |= ConfigManager.Instance.Config.SilentMode;
verboseMode |= ConfigManager.Instance.Config.VerboseMode;

// Before anything is read from ProgramData\ManagedBootstrap: a standard user can
// create files under ProgramData, and this process trusts what it finds there.
var dataDirectoryNotes = IsRunningAsAdministrator()
? DataDirectoryGuard.Secure()
: new List<string>();

Logger.Initialize(LogDirectory, Version, verboseMode, silentMode);
Logger.Debug("Main() called with arguments: " + string.Join(" ", args));
foreach (var note in dataDirectoryNotes)
{
Logger.Warning($"Data directory: {note}");
}
foreach (var retired in ConfigManager.Instance.RetiredSettingsPresent)
{
Logger.Warning($"Setting {retired} is ignored: it was never implemented and has been removed");
Expand Down Expand Up @@ -936,7 +946,7 @@ private static int SaveSettingsFromArgs(string[] args)
// never limited. The manifest and preflight are small; a throttled run
// downloads no item.
var throttle = BaselineThrottle.Evaluate(BaselineThrottle.Read(), DateTimeOffset.Now,
ConfigManager.Instance.Config.BaselineMinIntervalHours, forced);
ConfigManager.Instance.Config.BaselineMinIntervalHours, forced, Version);
if (throttle.Skip)
{
Logger.WriteSkipped($"Baseline throttle: skipping this run: {throttle.Reason}");
Expand Down
10 changes: 7 additions & 3 deletions README.md
Original file line number Diff line number Diff line change
Expand Up @@ -222,21 +222,25 @@ prompt.
Every baseline run downloads from the package host, so baselines are rate-limited.
The check runs only after the preflight has chosen baseline, so provisioning is never
limited. It reads `C:\ProgramData\ManagedBootstrap\baseline.json`, which holds the
last baseline's `end_time`, `status` and `consecutive_failures`. `last-run.json`
last baseline's `end_time`, `status`, `consecutive_failures`, the version that last
completed one (`tool_version`) and the version that last tried (`attempt_version`). `last-run.json`
cannot hold the clock, because every run rewrites it.

| Last baseline | Next baseline |
|---|---|
| Completed by another BootstrapMate version, and this version has not tried one | Runs |
| Interrupted (the run never recorded its end) | Runs at the next trigger |
| Completed less than `BaselineMinIntervalHours` ago (default 144) | Skips |
| Failed, partially failed or interrupted for the first time | One retry after 24 hours, never sooner |
| Failed or partially failed for the first time | One retry after 24 hours, never sooner |
| Failed again after that retry | Waits the full interval |
| None: a provisioning run clears the record | Runs |
| Any, with `C:\ProgramData\ManagedBootstrap\.bootstrap_force` present | Runs; the preflight consumes the file |

A throttled run fetches the manifest and runs the preflight, then downloads nothing.
It logs why, ends as `skip`, records SetupAssistant and Userland as `Skipped` in
`status.json`, and leaves `baseline.json` alone. `--force` does not bypass the
throttle. `BaselineMinIntervalHours` comes from policy or the settings registry
throttle, and BootstrapMate never relaunches itself: a retry comes only from the next
normal trigger (the Intune install or the daily Self-Heal task). `BaselineMinIntervalHours` comes from policy or the settings registry
(0-8760; 0 disables the limit for completed runs).

A baseline run also skips an item without downloading it when the manifest says
Expand Down
8 changes: 4 additions & 4 deletions RunReport.cs
Original file line number Diff line number Diff line change
Expand Up @@ -33,8 +33,8 @@ public static void Start(string version)
/// <summary>
/// A last-run.json still at "running" belongs to a run that died: this run holds the
/// single-instance lock, so none other is going. Its session is relabelled
/// "interrupted", and an interrupted baseline counts as a failed one, so the throttle
/// gives it one retry a day later instead of letting whatever killed it loop.
/// "interrupted", and so is the baseline record, which lets the next baseline run
/// straight away: the retry comes from the next normal trigger, never a relaunch.
/// </summary>
private static void RecoverInterruptedRun()
{
Expand All @@ -46,7 +46,7 @@ private static void RecoverInterruptedRun()
if (string.Equals(orphan.RunType, RunTypes.Baseline, StringComparison.OrdinalIgnoreCase))
{
var when = DateTimeOffset.TryParse(orphan.StartTime, out var started) ? started : DateTimeOffset.Now;
BaselineThrottle.Write(BaselineThrottle.After(BaselineThrottle.Read(), RunStatuses.Interrupted, when));
BaselineThrottle.Write(BaselineThrottle.After(BaselineThrottle.Read(), RunStatuses.Interrupted, when, orphan.ToolVersion));
}
}

Expand Down Expand Up @@ -97,7 +97,7 @@ public static void Finish(string? status = null)
// The baseline clock: a baseline sets it, a provisioning run clears it (a
// machine provisioned again starts over), a skip leaves it alone.
if (_record.RunType == RunTypes.Baseline)
BaselineThrottle.Write(BaselineThrottle.After(BaselineThrottle.Read(), outcome.Status, new DateTimeOffset(outcome.End)));
BaselineThrottle.Write(BaselineThrottle.After(BaselineThrottle.Read(), outcome.Status, new DateTimeOffset(outcome.End), _record.ToolVersion));
else if (_record.RunType == RunTypes.Provisioning && outcome.Status == RunStatuses.Completed)
BaselineThrottle.Clear();
}
Expand Down
18 changes: 18 additions & 0 deletions installer/Product.wxs
Original file line number Diff line number Diff line change
Expand Up @@ -80,6 +80,23 @@
<RegistryValue Root="HKLM" Key="SOFTWARE\BootstrapMate" Name="LastRunVersion" Value="$(var.FullVersion)" Type="string" />
</Component>

<!-- ProgramData\ManagedBootstrap holds what the SYSTEM run acts on: the force file,
cached installers, the ledger and run records. ProgramData lets any user create
files below it, so the folder gets its own ACL, not inherited: owner SYSTEM,
SYSTEM and Administrators full control, Users read. The CLI resets the same ACL
and removes anything a non-administrator created before every run. Permanent,
so an uninstall keeps the logs and records. -->
<StandardDirectory Id="CommonAppDataFolder">
<Directory Id="ManagedBootstrapDataDir" Name="ManagedBootstrap" />
</StandardDirectory>
<Component Id="DataDirectoryAcl" Directory="ManagedBootstrapDataDir" Permanent="yes"
Guid="7B2E4C1D-9A3F-4E58-B6D7-1C0F2A9E8B34">
<CreateFolder>
<PermissionEx Sddl="O:SYG:SYD:PAI(A;OICI;FA;;;SY)(A;OICI;FA;;;BA)(A;OICI;0x1200a9;;;BU)" />
</CreateFolder>
<RegistryValue Root="HKLM" Key="SOFTWARE\BootstrapMate" Name="DataDirectoryAcl" Value="1" Type="integer" KeyPath="yes" />
</Component>

<!-- Machine-level fallback settings: ConfigManager reads HKLM\SOFTWARE\BootstrapMate\Settings
when no CSP policy is present. CSP at HKLM\SOFTWARE\Policies\BootstrapMate still overrides. -->
<Component Id="MachineSettings" Directory="INSTALLDIR" Guid="C1F2B3A4-D5E6-4789-9012-A1B2C3D4E5F6">
Expand Down Expand Up @@ -155,6 +172,7 @@
<ComponentGroupRef Id="GuiAppFiles" />
<ComponentRef Id="RegistryEntries" />
<ComponentRef Id="MachineSettings" />
<ComponentRef Id="DataDirectoryAcl" />
<ComponentRef Id="SetPathComponent" />
<ComponentRef Id="StartMenuShortcut" />
<ComponentRef Id="LegacyStartMenuCleanup" />
Expand Down
2 changes: 1 addition & 1 deletion resources/en-US/BootstrapMate.adml
Original file line number Diff line number Diff line change
Expand Up @@ -87,7 +87,7 @@ Default: Disabled</string>
Default: C:\Program Files\BootstrapMate</string>

<string id="BaselineMinIntervalHours">Minimum Hours Between Baseline Runs</string>
<string id="BaselineMinIntervalHours_Help">A baseline run that starts less than this many hours after the last completed baseline exits as a skip before downloading anything. A failed, partially failed or interrupted baseline gets one retry after 24 hours, never sooner; if that retry fails too, the full interval applies. Provisioning runs are not limited. While C:\ProgramData\ManagedBootstrap\.bootstrap_force is present the limit does not apply; the preflight consumes the file.
<string id="BaselineMinIntervalHours_Help">A baseline run that starts less than this many hours after the last completed baseline exits as a skip before downloading anything. A new BootstrapMate version always gets a baseline. An interrupted baseline runs again at the next trigger. A failed or partially failed baseline gets one retry after 24 hours, never sooner; if that retry fails too, the full interval applies. Provisioning runs are not limited. While C:\ProgramData\ManagedBootstrap\.bootstrap_force is present the limit does not apply; the preflight consumes the file.

Range: 0-8760 hours
Default: 144 hours (6 days)</string>
Expand Down
50 changes: 39 additions & 11 deletions src/BootstrapMate.Core/BaselineThrottle.cs
Original file line number Diff line number Diff line change
Expand Up @@ -13,6 +13,10 @@ public sealed class BaselineRecord
[JsonPropertyName("end_time")] public string EndTime { get; set; } = "";
[JsonPropertyName("status")] public string Status { get; set; } = "";
[JsonPropertyName("consecutive_failures")] public int ConsecutiveFailures { get; set; }
/// <summary>The BootstrapMate version of the last completed baseline.</summary>
[JsonPropertyName("tool_version")] public string? ToolVersion { get; set; }
/// <summary>The BootstrapMate version of the last baseline, whatever its outcome.</summary>
[JsonPropertyName("attempt_version")] public string? AttemptVersion { get; set; }
}

/// <summary>
Expand All @@ -26,9 +30,14 @@ public sealed class BaselineRecord
/// <item>The <c>.bootstrap_force</c> file in ProgramData\ManagedBootstrap: run. The throttle
/// only looks; the preflight consumes it.</item>
/// <item>No record: run. A provisioning run clears the record.</item>
/// <item>This BootstrapMate is not the version that completed the last baseline, and has not
/// tried one yet: run. A new build always gets a baseline, whatever the interval; once it has
/// tried and failed, the failure rules below apply to it.</item>
/// <item>Last baseline was interrupted (it never recorded its end): run. The retry comes from
/// the next normal trigger; BootstrapMate never relaunches itself.</item>
/// <item>Last baseline completed less than <c>BaselineMinIntervalHours</c> ago (default 144): skip.</item>
/// <item>Last baseline failed, partially failed or was interrupted: one retry after 24 hours;
/// if that retry fails too, the full interval applies again.</item>
/// <item>Last baseline failed or partially failed: one retry after 24 hours; if that retry
/// fails too, the full interval applies again.</item>
/// </list>
/// A throttled run leaves the record alone, so the last real baseline stays the reference.
/// </remarks>
Expand All @@ -42,10 +51,18 @@ public static class BaselineThrottle

public sealed record Decision(bool Skip, string Reason);

public static Decision Evaluate(BaselineRecord? last, DateTimeOffset now, int minIntervalHours, bool forced)
public static Decision Evaluate(BaselineRecord? last, DateTimeOffset now, int minIntervalHours, bool forced, string currentVersion)
{
if (forced) return new(false, $"{ForceFilePath} is present");
if (last is null) return new(false, "no baseline recorded");
if (!string.Equals(last.ToolVersion ?? "", currentVersion, StringComparison.OrdinalIgnoreCase) &&
!string.Equals(last.AttemptVersion ?? "", currentVersion, StringComparison.OrdinalIgnoreCase))
{
var was = string.IsNullOrEmpty(last.ToolVersion) ? "an unrecorded version" : $"v{last.ToolVersion}";
return new(false, $"BootstrapMate v{currentVersion} has not completed a baseline (last completed by {was})");
}
if (string.Equals(last.Status, RunStatuses.Interrupted, StringComparison.OrdinalIgnoreCase))
return new(false, "last baseline was interrupted");
if (!DateTimeOffset.TryParse(last.EndTime, out var when))
return new(false, "last baseline has no readable time");

Expand All @@ -68,15 +85,26 @@ public static Decision Evaluate(BaselineRecord? last, DateTimeOffset now, int mi
return new(false, $"last baseline {last.Status} {age.TotalHours:F1}h ago (limit {wait.TotalHours:F0}h)");
}

/// <summary>The record a finished baseline leaves, counting failures in a row.</summary>
public static BaselineRecord After(BaselineRecord? previous, string status, DateTimeOffset end) => new()
/// <summary>
/// The record a baseline leaves. Failures and partial failures count in a row; an
/// interruption is not counted, since the run never got to fail. The version is the
/// one that last completed a baseline.
/// </summary>
public static BaselineRecord After(BaselineRecord? previous, string status, DateTimeOffset end, string version)
{
EndTime = end.ToString("yyyy-MM-ddTHH:mm:ss.fffzzz"),
Status = status,
ConsecutiveFailures = string.Equals(status, RunStatuses.Completed, StringComparison.OrdinalIgnoreCase)
? 0
: (previous?.ConsecutiveFailures ?? 0) + 1
};
bool completed = string.Equals(status, RunStatuses.Completed, StringComparison.OrdinalIgnoreCase);
bool interrupted = string.Equals(status, RunStatuses.Interrupted, StringComparison.OrdinalIgnoreCase);
return new()
{
EndTime = end.ToString("yyyy-MM-ddTHH:mm:ss.fffzzz"),
Status = status,
ConsecutiveFailures = completed ? 0
: interrupted ? previous?.ConsecutiveFailures ?? 0
: (previous?.ConsecutiveFailures ?? 0) + 1,
ToolVersion = completed ? version : previous?.ToolVersion,
AttemptVersion = version
};
}

private static readonly JsonSerializerOptions WriteOptions = new() { WriteIndented = true };

Expand Down
Loading
Loading