TL;DR

Create a role with no permissions that your account can assume, switch the session to its temporary keys, and run the script. Every call it makes that needs a permission is denied for real:

$identity  = Get-STSCallerIdentity
$partition = $identity.Arn.Split(':')[1]
$account   = $identity.Account
$trust = '{"Version":"2012-10-17","Statement":[{"Effect":"Allow","Principal":{"AWS":"arn:' + $partition + ':iam::' + $account + ':root"},"Action":"sts:AssumeRole"}]}'
New-IAMRole -RoleName denytest -AssumeRolePolicyDocument $trust
$previous = Get-AWSCredential
try {
    # A new role took about eight seconds to become assumable in testing.
    Start-Sleep -Seconds 8
    $delay = 1
    foreach ($attempt in 1..6) {
        try {
            $keys = (Use-STSRole -RoleArn "arn:${partition}:iam::${account}:role/denytest" -RoleSessionName denytest -ErrorAction Stop).Credentials
            break
        }
        catch {
            # Retry only the denial a new role gives; rethrow anything else, and the last denial.
            if ($_.Exception.InnerException.ErrorCode -ne 'AccessDenied' -or $attempt -eq 6) { throw }
            Start-Sleep -Seconds $delay
            $delay *= 2
        }
    }
    Set-AWSCredential -Credential $keys
    ./Your-Script.ps1
}
finally {
    # Restore your own credentials first; deleting the role needs them.
    if ($previous) { Set-AWSCredential -Credential $previous } else { Clear-AWSCredential }
    Remove-IAMRole -RoleName denytest -Force
}

AWS.Tools wraps the AWS error in an InvalidOperationException; the AccessDenied code is on $_.Exception.InnerException, not on $_.Exception.

A script that calls AWS will one day run with credentials that can’t do what it asks: a new role missing one permission, a scheduled task under the wrong profile. What it does then is usually untested, because the identity the script was written with can do everything.

I hit this while writing How to Publish a Custom CloudWatch Metric from PowerShell. Its common failures needed the exact message Write-CWMetricData prints when the caller isn’t allowed to publish. Removing a permission from my account to see one error was out, and so was publishing a real metric to watch it fail. This is the trick I used instead, and the exception details in this article come from those Write-CWMetricData runs.

A role with no permissions is a second identity that IAM denies for every action that needs a permission. A call made with its keys comes back with the genuine AccessDenied, and nothing is written or changed. The IAM Policy Simulator says whether a call would be denied; it doesn’t produce the exception a catch block has to handle.

Install the IAM and STS modules

New-IAMRole and Remove-IAMRole are in AWS.Tools.IdentityManagement; Get-STSCallerIdentity and Use-STSRole are in AWS.Tools.SecurityToken.

Install-Module -Name AWS.Tools.IdentityManagement, AWS.Tools.SecurityToken -Scope CurrentUser -Force
Import-Module AWS.Tools.IdentityManagement, AWS.Tools.SecurityToken

Create a role with no permissions

The trust policy decides who can assume the role. The partition and account come from your own ARN, so the same lines work in the standard, China and GovCloud partitions. Naming your account’s root lets any identity in the account with sts:AssumeRole permission assume the role. Yours can if its policy allows sts:AssumeRole on this role; an administrator’s does. No permission policy is attached, so the role is denied everything except calls that need no permission, such as Get-STSCallerIdentity, and resources whose own policy grants access to anyone.

$identity  = Get-STSCallerIdentity
$partition = $identity.Arn.Split(':')[1]
$account   = $identity.Account
$trust = '{"Version":"2012-10-17","Statement":[{"Effect":"Allow","Principal":{"AWS":"arn:' + $partition + ':iam::' + $account + ':root"},"Action":"sts:AssumeRole"}]}'
New-IAMRole -RoleName denytest -AssumeRolePolicyDocument $trust

Assume the role for temporary keys

Use-STSRole returns temporary credentials for the role; keep the Credentials property. A new role isn’t assumable straight away: in my test the first attempt was denied and the role became assumable about eight seconds later. Wait that long before the first call, which would otherwise be denied for certain, then retry with a backoff to cover a slower day. The loop waits 1, 2, 4, 8 and 16 seconds between attempts, retries only AccessDenied, and rethrows after the sixth attempt so a role you can’t assume fails instead of looping:

# A new role took about eight seconds to become assumable in testing.
Start-Sleep -Seconds 8
$delay = 1
foreach ($attempt in 1..6) {
    try {
        $keys = (Use-STSRole -RoleArn "arn:${partition}:iam::${account}:role/denytest" -RoleSessionName denytest -ErrorAction Stop).Credentials
        break
    }
    catch {
        # Retry only the denial a new role gives; rethrow anything else, and the last denial.
        if ($_.Exception.InnerException.ErrorCode -ne 'AccessDenied' -or $attempt -eq 6) { throw }
        Start-Sleep -Seconds $delay
        $delay *= 2
    }
}

Catch AccessDenied in the script

The cmdlet throws a System.InvalidOperationException whose InnerException is the AWS exception. That inner exception is an Amazon.Runtime.AmazonServiceException carrying ErrorCode AccessDenied, StatusCode Forbidden and ErrorType Sender. Test the inner exception, handle the denial, and rethrow anything else. $datum is the metric from your own script:

try {
    Write-CWMetricData -Namespace 'MyApp/Queue' -MetricData $datum -ErrorAction Stop
}
catch {
    $awsError = $_.Exception.InnerException
    if ($awsError -is [Amazon.Runtime.AmazonServiceException] -and $awsError.ErrorCode -eq 'AccessDenied') {
        Write-Warning "No permission to publish the metric: $($awsError.Message)"
    }
    else {
        throw
    }
}

Run the script as the role

Set-AWSCredential -Credential makes the role’s keys the default for the session, so the script runs unmodified. Every call in it that needs a permission is denied. Get-AWSCredential with no arguments returns the session’s current credentials, so save them first and put them back after. Clear-AWSCredential alone would only remove the role’s keys, not restore what was there before, and the Remove-IAMRole that follows needs your own access. When nothing was set, clearing is right: later calls fall back to your default profile or environment. The restore sits in finally because the script is expected to fail: without it, an unhandled denial skips the restore, the session stays on the role’s keys, and the cleanup that follows is denied too. The script’s error still reaches you.

$previous = Get-AWSCredential
Set-AWSCredential -Credential $keys
try { ./Your-Script.ps1 }
finally { if ($previous) { Set-AWSCredential -Credential $previous } else { Clear-AWSCredential } }

To deny a single call instead, pass the keys to that cmdlet with -Credential $keys.

Delete the role

Remove-IAMRole -RoleName denytest -Force

Run this with your own credentials restored. In a script, put it in the same finally as the restore, after it, as the answer block at the top does. The role is then deleted even when the script under test or the assume fails, and the error still reaches you.

The temporary keys expire on their own, and the role they belonged to is gone.

Expected result

The script’s handler runs instead of an unhandled error. Without a handler, the call fails with the error an under-permissioned identity gets:

Write-CWMetricData: User: arn:aws:sts::<account-id>:assumed-role/denytest/denytest is not authorized to perform: cloudwatch:PutMetricData because no identity-based policy allows the cloudwatch:PutMetricData action

The message names the assumed role and session, the refused action and the reason. Replace the account ID before you share it.

After the role is deleted, a second Remove-IAMRole confirms it’s gone:

Remove-IAMRole: The role with name denytest cannot be found.

Common failures

Use-STSRole is denied

User: arn:aws:iam::<account-id>:user/<user-name> is not authorized to perform: sts:AssumeRole on resource: arn:aws:iam::<account-id>:role/denytest

STS prints the same message whether the role was created seconds ago, doesn’t exist, or exists but won’t let you in, so the message alone doesn’t say which. Check them in that order: let the backoff run after New-IAMRole, confirm the role with Get-IAMRole -RoleName denytest, then confirm your own policy allows sts:AssumeRole on it. The inner exception is an Amazon.SecurityToken.AmazonSecurityTokenServiceException with ErrorCode AccessDenied, wrapped the same way as CloudWatch’s.

ErrorCode is empty in the catch block

$_.Exception is the InvalidOperationException wrapper, which carries no AWS fields. Read ErrorCode, StatusCode and Message from $_.Exception.InnerException. A typed catch [Amazon.CloudWatch.AmazonCloudWatchException] does match the wrapped error, so the type works as a filter.

Script still runs with full access

The script sets its own credentials, with -ProfileName or Set-AWSCredential inside it, which override the session default. If the script takes a credential parameter, pass $keys to it; otherwise run its calls with -Credential $keys.

TL;DR

$LASTEXITCODE is not the success status of the last PowerShell cmdlet. Use it for a native executable such as aws.exe, and capture it immediately:

aws --version
$Code = $LASTEXITCODE
if ($Code -ne 0) { throw "AWS CLI exited with code $Code" }

For a cmdlet, use PowerShell error handling:

Get-Item -LiteralPath 'C:\Data\settings.json' -ErrorAction Stop

-ErrorAction Stop turns a cmdlet’s non-terminating error into a terminating one, which stops the script or reaches an enclosing catch.

While working on a backup script for my 7 Days to Die game server, I thought it would be good to share this.

You replace an AWS CLI command with a PowerShell cmdlet and keep the success check. The cmdlet prints an error. The script announces success anyway.

The check still runs. It’s reading the result of a different operation.

Reproduce a failed command with exit code zero

Run this in PowerShell on Windows:

cmd.exe /d /c exit 0
Write-Error 'Demonstration: the upload failed' -ErrorAction Continue
"Native exit code: $LASTEXITCODE"

The error appears, followed by:

Native exit code: 0

The zero came from cmd.exe. Write-Error did not update it. The explicit Continue makes this demonstration non-terminating even if your session normally uses a stricter error preference.

The reverse is just as misleading:

cmd.exe /d /c exit 7
Get-Date | Out-Null
"Native exit code: $LASTEXITCODE"

This prints 7 even though Get-Date succeeded. These examples illustrate why a value left in the variable is not evidence about a later cmdlet.

Microsoft defines the variable for native programs and PowerShell scripts; script behavior also depends on invocation and the exit keyword. Ordinary cmdlet success or failure does not make it a universal status register. See about_Automatic_Variables (opens in a new tab).

For native commands, check each result at the boundary

This example assumes AWS CLI is installed, the source exists, and the active AWS identity can access your chosen bucket:

$Source = 'C:\Data\exports'
$Destination = 's3://YOUR-BUCKET/exports/'

$null = Get-Command aws -CommandType Application -ErrorAction Stop
aws s3 sync $Source $Destination
$Code = $LASTEXITCODE

if ($Code -ne 0) {
    throw "S3 sync did not complete cleanly; AWS CLI exit code $Code"
}

'Export transfer completed'

Replace YOUR-BUCKET before running it. AWS documents nonzero outcomes including failed S3 transfers and skipped files. A skipped file is enough to reject a backup run as incomplete; inspect the command output for the cause. See the AWS CLI return-code reference (opens in a new tab).

Capture and handle each result before moving on.

Also distinguish a process failure from a launch failure. If aws is not found, no AWS CLI process returned an exit code, and the check reads whatever an earlier native command left. The Get-Command line stops the script before that can happen.

Why try/catch sometimes misses a cmdlet error

PowerShell can report an error while continuing execution. For example:

try {
    Write-Error 'Demonstration failure' -ErrorAction Continue
    'Still inside try'
}
catch {
    'Caught the error'
}

The error is displayed and Still inside try prints. The catch block isn’t entered. Change that one invocation to -ErrorAction Stop and the catch block runs instead.

Some errors already terminate execution; they don’t need this promotion. -ErrorAction Stop makes the intended behavior explicit for cmdlet errors that would otherwise continue. Microsoft’s try/catch documentation (opens in a new tab) explains which errors those blocks handle.

Catch a Write-S3Object failure with -ErrorAction Stop

With AWS.Tools.S3 installed and AWS access configured, use this for an intentional upload of one existing file:

Import-Module AWS.Tools.S3 -ErrorAction Stop

try {
    Write-S3Object -BucketName 'YOUR-BUCKET' `
        -File 'C:\Data\exports\report.json' `
        -Key 'exports/report.json' `
        -ErrorAction Stop

    'Upload completed'
}
catch {
    Write-Warning ("Upload failed: {0}" -f $_.Exception.Message)
    throw
}

The success message is reachable only after the upload returns normally. The bare throw propagates the caught error to the caller. Logging and then continuing would hide the failure from whatever invoked the script.

If you have no context to add and no recovery to attempt, remove the try/catch and keep -ErrorAction Stop. A catch block that only rethrows isn’t required.

$PSNativeCommandUseErrorActionPreference in PowerShell 7

PowerShell 7.4 added $PSNativeCommandUseErrorActionPreference. When it’s $true, nonzero native exit codes produce PowerShell errors governed by $ErrorActionPreference; with Stop, those can reach catch. The default is $false. Microsoft documents it in about_Preference_Variables (opens in a new tab).

That doesn’t make -ErrorAction Stop a parameter for aws.exe. Passed to a native program, it’s an argument for that program to interpret. Explicit exit-code checks remain useful for scripts spanning Windows PowerShell 5.1 and PowerShell 7, and for tools whose nonzero codes have special meanings.

If native error promotion is enabled with Stop, execution can leave the native invocation before the following explicit check. Either path must preserve the failure; don’t catch it and then print success.

Common failures

LASTEXITCODE is empty or stale. There may be no relevant native result in the session. Choose the error mechanism for the operation you actually ran.

Can I replace it with $? everywhere? $? describes the last command’s execution status and is overwritten by the next command. It isn’t a durable record of a multi-step job. Structured error handling is clearer for cmdlets.

The task still reports success. Check whether a wrapper catches and suppresses the error, then exits normally. At the outer script boundary, preserve a failure through an unhandled terminating error or an intentional nonzero exit code.

A script needs to remember whether the work succeeded. That starts by listening to the failure signal the command actually provides.

TL;DR

Open the PowerShell edition your automation uses as Administrator, then install the modular S3 package for all users:

Install-Module -Name AWS.Tools.Installer -MinimumVersion 2.0.0 -MaximumVersion 2.9.999 `
    -Repository PSGallery -Scope AllUsers -Force
Import-Module AWS.Tools.Installer -MinimumVersion 2.0.0 -MaximumVersion 2.9.999 `
    -ErrorAction Stop
Install-AWSToolsModule -Name AWS.Tools.S3 -Version '5.*' -Scope AllUsers

Swap AWS.Tools.S3 for the service module your script calls. An older 1.x installer may already be there, and 1.x has no -Version parameter, so the last line would fail with it. Without -Force, Install-Module only warns that 1.x is already installed and leaves it. With -Force it installs 2.x beside it, and the import line loads 2.x rather than 1.x. -MaximumVersion 2.9.999 on both lines, as in AWS’s own install command, keeps a future 3.x out of a workflow written for 2.x. Keep -Version '5.*'. Without it the installer takes the latest major version, which can carry breaking changes, as AWS’s Installer v2 announcement (opens in a new tab) warns. With -Name it installs only the modules you name plus AWS.Tools.Common, and leaves other AWS.Tools modules at their versions, so name every module your tasks use together if they should move in step.

In Windows PowerShell 5.1, run this first:

$protocol = [Net.ServicePointManager]::SecurityProtocol
$tls12 = [Net.SecurityProtocolType]::Tls12
if ($protocol -ne 'SystemDefault' -and -not ($protocol -band $tls12)) {
    [Net.ServicePointManager]::SecurityProtocol = $protocol -bor $tls12
}
Install-PackageProvider -Name NuGet -MinimumVersion 2.8.5.201 -Force | Out-Null

The if adds TLS 1.2 only when the session has neither it nor the operating system’s default. It never removes a protocol, and it leaves the OS default alone, as Microsoft’s TLS guidance (opens in a new tab) recommends, since that default can negotiate newer versions. The gallery needs TLS 1.2, as Microsoft’s PowerShell Gallery TLS post (opens in a new tab) explains, and so does the NuGet provider download, which is why the check comes first. On the test server it changed nothing. The last line installs the NuGet provider, and does nothing where it’s already in place. If the gallery still can’t be reached after both, TLS isn’t the cause; look at a proxy, DNS or a firewall. An install that reaches the gallery and then fails is a different problem, such as the .NET or PowerShellGet version the package requires.

Verify from a fresh session under the account that runs the task:

Import-Module AWS.Tools.S3 -ErrorAction Stop
(Get-Module AWS.Tools.S3).ModuleBase

The path should start $env:ProgramFiles\WindowsPowerShell\Modules\ for Windows PowerShell, or $env:ProgramFiles\PowerShell\Modules\ for PowerShell 7. That’s C:\Program Files for a 64-bit host and C:\Program Files (x86) for a 32-bit one.

The script works in your terminal. Task Scheduler reports that Write-S3Object isn’t recognized.

Before rewriting the script, check where you installed its dependencies. A module beneath your Documents folder is an installation for you. The scheduled task may run as someone else, using a different PowerShell executable.

Choose AWS.Tools for a new installation

AWS currently recommends AWS.Tools, with separate service modules such as AWS.Tools.S3 and a shared AWS.Tools.Common dependency. The installer manages dependencies and coordinates service-module versions. Follow the AWS modular installation guide (opens in a new tab) for that workflow.

For a script that uploads to S3, install S3. Add AWS.Tools.EC2 or another service module when the script actually uses it.

The Windows installation options also include the large AWSPowerShell.NetCore module and the legacy Windows-specific AWSPowerShell module. They are separate packaging choices, not three prerequisites to install together. AWS lists them in its Windows setup overview (opens in a new tab).

Use the same PowerShell host as the scheduled task

Check the shell before installing:

$PSVersionTable | Select-Object PSVersion, PSEdition
(Get-Process -Id $PID).Path
$env:PSModulePath -split ';'

For new automation, use a supported PowerShell 7 release. For an existing Windows PowerShell 5.1 task, verify package and .NET requirements before changing its dependencies. Do not assume a package’s major-version upgrade is only a packaging change.

Typical system-wide module locations differ:

PowerShell discovers modules through $env:PSModulePath, and the sharing runs one way: PowerShell 7 also searches the Windows PowerShell AllUsers folder, but Windows PowerShell never searches PowerShell 7’s. A successful import in one edition is not proof that the other can load the same installation. Microsoft documents the defaults and startup behavior in about_PSModulePath (opens in a new tab).

Check the executable configured in Task Scheduler, including its architecture: a 32-bit powershell.exe resolves Program Files to Program Files (x86). Use that host for the verification below.

Install once in an elevated session

Run the commands in the answer box. Keep -Scope AllUsers on both installation commands: installing the installer globally does not make the service package’s scope implicit.

Install-Module comes from PowerShellGet. If it is missing, provision PowerShellGet before running this workflow; an older installation may prompt for a NuGet provider. Check that the repository is the one you intend to use:

Get-Command Install-Module
Get-PSRepository -Name PSGallery

Review the Gallery prompt when it appears. A one-time installation does not require changing the repository’s trust policy permanently. The installer itself comes from PSGallery, but Install-AWSToolsModule downloads the service modules as one archive from sdk-for-net.amazonwebservices.com, which its help says, and not from PSGallery. A server behind a proxy needs that host allowed as well as the Gallery’s own, which Microsoft lists under network access to the PowerShell Gallery (opens in a new tab). Microsoft’s Install-Module documentation (opens in a new tab) explains scope, repository selection, and installation prompts.

The installer pulls in AWS.Tools.Common with S3. You do not need to install every AWS module. The example also omits -CleanUp, which removes older module versions; decide on cleanup after checking whether existing jobs pin them.

Verify the module loads as the task account

Close the elevated session. You can’t open a console as SYSTEM, and a scheduled task keeps none of its output. Put these lines at the top of the task’s script, start it with Start-ScheduledTask, and read the log it writes:

& {
    [Security.Principal.WindowsIdentity]::GetCurrent().Name
    $env:PSModulePath -split ';'

    Get-Module -ListAvailable AWS.Tools.Common, AWS.Tools.S3 |
        Select-Object Name, Version, ModuleBase | Format-Table -AutoSize

    Import-Module AWS.Tools.S3 -ErrorAction Stop
    (Get-Module AWS.Tools.S3).ModuleBase
} *> (Join-Path $env:ProgramData 'aws-tools-check.log')

Run as SYSTEM, the first line prints NT AUTHORITY\SYSTEM. On the test server SYSTEM’s module path had no Documents folder in it at all. Where it has one, it’s SYSTEM’s own profile, not yours, so a module you installed for yourself is invisible to the task either way. The -ListAvailable call lists every copy the account can find; more than one row per module means more than one installation. The last line is the copy that actually loaded. These checks load code and resolve a command; they do not contact S3.

For unattended work, put the explicit import in the script. That gives a missing or incompatible dependency a clear failure point before any work starts.

Where AWSPowerShell.NetCore still fits

An existing script may explicitly import AWSPowerShell.NetCore. If retaining that package is part of maintaining the script, install it from the appropriate elevated host:

Install-Module -Name AWSPowerShell.NetCore -Repository PSGallery -Scope AllUsers

That’s an alternative to the modular path. Start a fresh session before switching package families; loading overlapping AWS assemblies and command names complicates diagnosis. AWS still documents AWSPowerShell.NetCore installation (opens in a new tab), while directing new installations to AWS.Tools.

Common failures

Installation fails with access denied

The installation session isn’t elevated. The ordinary task doesn’t need administrator rights merely because an administrator installed its dependencies.

Module installed, but the task can’t find it

Compare the task’s executable, account, module path, and ModuleBase with your interactive session. Use the same verification commands in the task’s diagnostic output.

Import fails because script execution is disabled

Inspect Get-ExecutionPolicy -List and follow the machine’s approved policy. Installation scope and script-execution policy solve different problems.

Import works, but AWS reports missing credentials or access denied

The installation is no longer the issue. Configure authentication for the task’s identity and verify its permissions. Your interactive profile isn’t evidence that another account has working AWS access.

The useful completion check is the task account loading the expected module in the expected shell. An installer success message is only the first step.

TL;DR

aws s3 sync compares a source and destination before selecting transfers. Write-S3Object -Folder -Recurse uploads every file in the folder hierarchy on every run; recursion adds subfolders, not a destination comparison or deletion pass.

Keep sync when your script depends on skipping files that already match. Use Write-S3Object when uploading every selected file is the intended operation. Changing tools also means changing error handling: native exit codes for the CLI, PowerShell errors for the cmdlet.

The refactor looks harmless. Replace one external command with a PowerShell cmdlet, run it, and confirm that the files appear in S3.

The first run proves little. The second run is where the behaviors separate.

Two commands that can produce the same first upload

The following are alternatives, run from PowerShell. They assume an existing source folder, a bucket you control, and configured AWS access. Replace the bucket placeholder. The first needs AWS CLI; the second needs AWS.Tools.S3.

$Source = 'C:\Data\exports'
$Bucket = 'YOUR-BUCKET'

$null = Get-Command aws -CommandType Application -ErrorAction Stop
aws s3 sync $Source "s3://$Bucket/exports/"
$Code = $LASTEXITCODE
if ($Code -ne 0) { throw "S3 sync exited with code $Code" }

$Source = 'C:\Data\exports'
$Bucket = 'YOUR-BUCKET'

Import-Module AWS.Tools.S3 -ErrorAction Stop
Write-S3Object -BucketName $Bucket -Folder $Source `
    -KeyPrefix 'exports/' -Recurse -ErrorAction Stop

For a source containing report.json and daily\summary.csv, the intended keys are exports/report.json and exports/daily/summary.csv. Keep the prefix fixed when comparing repeated runs; a new prefix gives either command an empty destination namespace.

AWS describes the cmdlet as an uploader for files, content, or folder trees. -Recurse includes subfolders. It doesn’t implement the CLI’s sync algorithm. See the Write-S3Object reference (opens in a new tab).

What each command does on a repeat run

For local-to-S3 sync, the default upload criteria are a missing destination object, a different size, or a local modification time newer than the S3 object’s last-modified time. That time is when the object was uploaded. It isn’t a byte-for-byte scan of every file. A same-size file restored or copied with its original, older timestamp is skipped, and S3 keeps the stale bytes. --size-only discards the time criterion; --exact-timestamps applies to S3-to-local sync. These rules and directions are documented in the AWS CLI sync reference (opens in a new tab).

This is the migration question: did your script promise to upload a collection of files, or did it promise to transfer only what its comparison considers changed? Similar-looking final keys don’t answer that question.

Deletions are a separate decision

Deleting a local file doesn’t remove its S3 object in either example above. For the CLI, --delete explicitly adds destination cleanup. Preview that choice before applying it:

aws s3 sync 'C:\Data\exports' 's3://YOUR-BUCKET/exports/' --delete --dryrun
$Code = $LASTEXITCODE
if ($Code -ne 0) { throw "Sync preview exited with code $Code" }

The preview reports proposed operations; it isn’t proof that subsequent writes or deletions will be authorized or succeed. Review the exact bucket and prefix before removing --dryrun.

For backups, destination-only files create another issue: restoring all current objects can resurrect files that were intentionally removed locally. Decide whether you need a current mirror or recoverable snapshots before choosing how to handle that case.

Repeated uploads in a versioned bucket

In a bucket with versioning enabled, another successful overwrite creates another object version. Each stored version is a complete object, not only the changed bytes. AWS explains this in its S3 Versioning guide (opens in a new tab).

Consequently, repeatedly uploading an unchanged tree can create redundant versions as well as extra transfer work and requests. How much that matters depends on your data and schedule. A small configuration directory and a large export tree need different tradeoffs.

Conversely, a fresh timestamped prefix intentionally stores a new set of keys. There’s no previous tree there for sync to reuse. For that design, uploading every file may be exactly what you want.

Neither approach makes a live folder an atomic snapshot. If several related files change during the transfer, the destination can contain a mixture of moments. Use an application-consistent export or stable staging directory when a restore requires the files to agree with each other.

Preserve the failure contract when changing tools

The CLI example checks its result immediately. A final check after several native commands can miss an earlier failure. AWS’s return-code documentation (opens in a new tab) includes failed and skipped S3 transfers among nonzero outcomes.

For the cmdlet, add context and propagate the error if needed:

try {
    Write-S3Object -BucketName $Bucket -Folder $Source `
        -KeyPrefix 'exports/' -Recurse -ErrorAction Stop
}
catch {
    Write-Warning ("Export upload failed: {0}" -f $_.Exception.Message)
    throw
}

Don’t leave an old $LASTEXITCODE check after the cmdlet. The separate PowerShell error-handling article shows why that can report success for a failed upload.

Check a migration before trusting the replacement

Use a disposable source folder and dedicated destination prefix:

1. Upload two files and record their destination keys.
2. Repeat without editing either file; inspect actual uploads or object versions.
3. Change one file’s size and repeat; check which objects are written.
4. Remove one local file; inspect the destination-only object.
5. Use a missing source path and verify the overall script fails.
6. Use a -SearchPattern that matches nothing and confirm the script notices. Write-S3Object uploads nothing and reports no error.

Those checks exercise the behavior a syntax translation can overlook. They also make your deletion and repeat-run expectations explicit.

When each is the wrong choice

aws s3 sync is the wrong choice when:

• A file can come back with its size and an older timestamp, as a restore or a copy that keeps times does. The comparison skips it, and the destination keeps the old bytes.
• You add --delete on a prefix that other jobs also write to. The reconciliation removes their objects because they are absent from your source.
• Every run writes to a fresh prefix, such as a dated snapshot. There’s nothing there to compare against, so the comparison buys nothing and the script still depends on the AWS CLI.

Write-S3Object -Folder -Recurse is the wrong choice when:

• The script relies on skipping files that haven’t changed. Every run uploads the whole tree again, and in a versioned bucket each upload is another complete version.
• The destination has to mirror the source, deletions included. The cmdlet never removes destination-only objects, and adding that means owning comparison rules, key mapping, filters, deletions and partial failures yourself.
• You need to see what a run will do before it runs. There’s no equivalent of --dryrun.

Choose based on the repeat run and the restore you need.

TL;DR

A daily scheduled task runs a PowerShell script as SYSTEM. The script zips Saves and serverconfig.xml, writes the archive to S3 with Write-S3Object as STANDARD_IA, and keeps three archives locally and thirty days in the bucket. Every part is stock: Compress-Archive, AWS Tools for PowerShell, Task Scheduler.

SYSTEM has its own profile, so install the modules and write the credentials where it can reach them, not where your own session puts them.

I’ve played 7 Days to Die since it came out, and years ago I set up my own dedicated server, on the Windows Server 2019 VM it still runs on. For a long time I updated and managed it by hand. Then one day I realized I knew how to do it better, and started automating it.

The big part was updates. When it’s time to play, the server should already be up to date. There’s nothing worse than getting ready to play and hitting the update wait.

The goal is a server I can replace without a second thought, starting with a move to Windows Server 2025, and backups are the first step. Steam can reinstall the game on any machine, but it can’t give back the world: the map, the players’ bases and everything in their inventories. So every morning, ahead of the update window, a scheduled task zips that part and copies it to S3, where a new server can pick it up.

S3 because I already use it and like it. Nothing about the backup needs S3. The zip, the schedule, the local retention and the logging work the same with another drive or a share on a NAS or SAN, and Use a different destination covers what changes. The VM runs outside AWS, which is why credentials take a step of their own: there’s no instance role to lean on.

What to back up

Two things hold state. The game writes the world, the players and their inventories under Saves, and the server’s settings live in serverconfig.xml beside it. On this server both are under C:\7DaysToDieServer. A server installed with the defaults keeps Saves under %APPDATA%\7DaysToDie of the account that runs the game instead, unless UserDataFolder in serverconfig.xml moves it. The script looks for Saves beside serverconfig.xml and stops when it isn’t there; on a default install, pass the full path to Saves as -SavesDir in step 5. Everything else in the server directory is the Steam installation, which SteamCMD reproduces on demand, and it’s most of the disk. The backup takes those two and nothing else, so the zip comes out at about 23 MB.

This server runs Navezgane, the shipped map. A random-gen world also keeps its terrain in GeneratedWorlds, beside Saves, and a new server can’t rebuild the world without it, so add that directory to the archive and the restore.

1. Install AWS Tools where SYSTEM can see them

The script reaches S3 through AWS Tools for PowerShell rather than the CLI. -Scope AllUsers is the part that matters. A per-user install lands under your own Documents folder, which SYSTEM cannot see, so the scheduled run fails to import the modules while your own runs work.

On a fresh Server 2019 the gallery needs the NuGet provider first. The TLS check before it adds TLS 1.2 only when the session has neither it nor the OS default, so it never removes a protocol. On Server 2019 it changes nothing; installing AWS Tools for all users explains when it matters:

$protocol = [Net.ServicePointManager]::SecurityProtocol
$tls12 = [Net.SecurityProtocolType]::Tls12
if ($protocol -ne 'SystemDefault' -and -not ($protocol -band $tls12)) {
    [Net.ServicePointManager]::SecurityProtocol = $protocol -bor $tls12
}
Install-PackageProvider -Name NuGet -MinimumVersion 2.8.5.201 -Force | Out-Null
Install-Module -Name AWS.Tools.Installer -Repository PSGallery -Scope AllUsers -Force
Install-AWSToolsModule -Name AWS.Tools.S3, AWS.Tools.SecurityToken -Scope AllUsers -CleanUp -Force

Confirm they landed in the machine path rather than your profile:

Get-Module -ListAvailable AWS.Tools.S3 | Select-Object Name, Version, Path

Path should start C:\Program Files\WindowsPowerShell\Modules\.

2. Give SYSTEM its own AWS credentials

The task runs as SYSTEM so it works whether or not anyone is signed in. SYSTEM is a separate account with a separate profile, and the AWS Tools read credentials from the profile of whoever is running them. Anything you run in your own session writes to %USERPROFILE%\.aws\; SYSTEM never sees that.

A CloudFormation template creates both the bucket and a user who can reach only that bucket. Save it as backup-stack.yaml:

AWSTemplateFormatVersion: '2010-09-09'
Description: >-
  An S3 bucket for a game server's world backups and an IAM user that can do
  only what the backup and restore scripts do: list the bucket, write, read
  and delete its own archives. Archives expire after RetentionDays.

Metadata:
  AWSToolsMetrics:
    AWSAgentToolkit: aws-cloudformation@2

Parameters:
  RetentionDays:
    Type: Number
    Default: 30
    MinValue: 1
    Description: Days an archive stays in the bucket before S3 deletes it.

Resources:
  BackupBucket:
    Type: AWS::S3::Bucket
    DeletionPolicy: Retain
    UpdateReplacePolicy: Retain
    Metadata:
      com.aws.cloudformation.Context:
        why: Holds the server's backup archives; retained on stack deletion so deleting the stack never deletes backups.
        must: Never public. The expiry rule keeps running when the server, and its own pruning, does not.
    Properties:
      PublicAccessBlockConfiguration:
        BlockPublicAcls: true
        BlockPublicPolicy: true
        IgnorePublicAcls: true
        RestrictPublicBuckets: true
      BucketEncryption:
        ServerSideEncryptionConfiguration:
          - ServerSideEncryptionByDefault:
              SSEAlgorithm: AES256
      LifecycleConfiguration:
        Rules:
          - Id: ExpireArchives
            Status: Enabled
            ExpirationInDays: !Ref RetentionDays
            AbortIncompleteMultipartUpload:
              DaysAfterInitiation: 3

  BackupBucketPolicy:
    Type: AWS::S3::BucketPolicy
    Metadata:
      com.aws.cloudformation.Context:
        why: Refuses any request that is not over HTTPS.
    Properties:
      Bucket: !Ref BackupBucket
      PolicyDocument:
        Version: '2012-10-17'
        Statement:
          - Sid: DenyInsecureTransport
            Effect: Deny
            Principal: '*'
            Action: 's3:*'
            Resource:
              - !GetAtt BackupBucket.Arn
              - !Sub '${BackupBucket.Arn}/*'
            Condition:
              Bool:
                'aws:SecureTransport': 'false'

  BackupUser:
    Type: AWS::IAM::User
    Metadata:
      com.aws.cloudformation.Context:
        why: The identity the server's backup task and a restore run as. Its access key is created after the stack, so the secret never passes through CloudFormation.
        must: No console access and no permission outside this one bucket.
    Properties:
      Policies:
        - PolicyName: BackupAndRestore
          PolicyDocument:
            Version: '2012-10-17'
            Statement:
              - Sid: ListTheBucket
                Effect: Allow
                Action: 's3:ListBucket'
                Resource: !GetAtt BackupBucket.Arn
              - Sid: WriteReadPruneArchives
                Effect: Allow
                Action:
                  - 's3:PutObject'
                  - 's3:GetObject'
                  - 's3:DeleteObject'
                Resource: !Sub '${BackupBucket.Arn}/*'

Outputs:
  BucketName:
    Description: Goes on the first line of backup-config.txt.
    Value: !Ref BackupBucket
  UserName:
    Description: Create its access key with New-IAMAccessKey -UserName <this>.
    Value: !Ref BackupUser

It creates three things:

• A private bucket. All public access is blocked, requests over plain HTTP are refused, and an archive expires after RetentionDays. The expiry rule keeps running when the script doesn’t, and it also removes the fragments an interrupted upload leaves, which are billed until removed. CloudFormation leaves the bucket in place if you delete the stack.
• A user with no console access and no access key. The key comes from a separate command, so the secret never passes through CloudFormation.
• A policy scoped to the one bucket. ListBucket acts on the bucket and the object actions act on its contents, so the two resource lines differ. Swapping them gets you AccessDenied.

PutObject writes the archive and DeleteObject is for the script’s prune. Reading each upload back to check it arrived is a listing, so ListBucket covers that. GetObject is only for restoring, and it lets the same credentials restore on a new machine. With it removed from the policy, a download as SYSTEM failed with is not authorized to perform: s3:GetObject, while listing the bucket still worked. The cost is that a stolen key can read your old archives, which a write-only key could not.

Deploy it from your own session, with your own credentials. The backup user’s policy can’t create a bucket or a user, and it shouldn’t. The stack creates an IAM user, so it needs CAPABILITY_IAM. The commands come from the AWS.Tools.CloudFormation and AWS.Tools.IdentityManagement modules, which you install the way step 1 installs the others:

$stackName = 'game-server-backups'
$region = 'us-west-2'
$template = Get-Content .\backup-stack.yaml -Raw
New-CFNStack -StackName $stackName -TemplateBody $template -Capability CAPABILITY_IAM `
    -Region $region
Wait-CFNStack -StackName $stackName -Region $region -Timeout 300 `
    -Status CREATE_COMPLETE, ROLLBACK_COMPLETE
(Get-CFNStack -StackName $stackName -Region $region).Outputs |
    Select-Object OutputKey, OutputValue

The bucket is created in the stack’s region, and the backup task calls the region in SYSTEM’s config file below, so use the same one in both places.

Add -Parameter @{ ParameterKey = 'RetentionDays'; ParameterValue = '60' } to New-CFNStack to change the 30-day default. The script prunes too, at its own -S3KeepDays, which is 30 unless you pass another number, so add the same number to the task’s arguments in step 5. Otherwise the script deletes archives the bucket would have kept. The outputs are BucketName, which step 3 uses, and UserName. I haven’t run these cmdlets. The stack this template makes was created through the CloudFormation API with CAPABILITY_IAM, and it reached CREATE_COMPLETE with both outputs and the default of 30 days.

Create the user’s access key. The secret is shown once, so keep the output out of any log:

New-IAMAccessKey -UserName '<UserName output>'

I didn’t run that command either. The key isn’t part of the stack, but deleting the test stack with its key still in place removed the user and the key together and left the bucket with its archives, so there is no separate step to undo it.

Then, from an elevated PowerShell, write that key where SYSTEM will look for it: two ini-format files, written by hand. You need both. The second carries the region, and without a region every call fails, however good the keys are.

$systemAws = 'C:\Windows\System32\config\systemprofile\.aws'
New-Item -ItemType Directory -Path $systemAws -Force | Out-Null

@"
[default]
aws_access_key_id = AKIA...
aws_secret_access_key = ...
"@ | Set-Content -Path "$systemAws\credentials" -Encoding ascii

@"
[default]
region = us-west-2
"@ | Set-Content -Path "$systemAws\config" -Encoding ascii

The directory is hidden, so dir does not show it; Get-ChildItem -Force does.

Two shortcuts look like they would do this and do not:

• Set-AWSCredential -StoreAs writes to the SDK’s own encrypted store under AppData, not to these files. That store belongs to the Windows account that wrote it.
• Set-DefaultAWSRegion lasts only for the session that ran it, so the region is gone by the time the task runs.

If you would rather not write into SYSTEM’s profile, -ProfileLocation points a call at a credentials file anywhere on disk. You then have to pass it on every call, which suits a script you are writing more than one you are copying.

3. Name the bucket for the script

Write the BucketName output on the first line of backup-config.txt, beside the script. The script reads it from there, so the script itself holds nothing specific to your account. The examples in the rest of this article show 7dtd-server-backups where yours goes.

4. Save the script

Save this as C:\Scripts\backup-s3.ps1, next to backup-config.txt. Each step that could leave you without a backup stops the run where it failed, and the exit code says how far it got:

• 0: the backup is in the bucket and old copies are pruned.
• 1: no backup could be confirmed in the bucket.
• 2: the backup is in the bucket, but pruning failed.

Task Scheduler shows that number as Last Run Result, so you can spot a partial run without opening the log.

<#
.SYNOPSIS
    Back up a 7 Days to Die dedicated server's saves to Amazon S3.

.DESCRIPTION
    Zips Saves and serverconfig.xml, writes the zip to S3 as STANDARD_IA,
    keeps three zips locally and thirty days in the bucket, keeps thirty days
    of logs. One log per run under <ServerDir>\backup-logs.

    S3 is reached through AWS Tools for PowerShell (AWS.Tools.S3 and
    AWS.Tools.SecurityToken), installed with -Scope AllUsers so the account the
    task runs as can import them. Runs as SYSTEM from Task Scheduler, so the
    credentials and region it uses are SYSTEM's, from:
    C:\Windows\System32\config\systemprofile\.aws\ (credentials and config).

    Exit codes: 0 success, 1 the backup could not be confirmed in S3, 2 the
    backup is in S3 but a prune step failed.
#>
[CmdletBinding()]
param(
    [string]$ServerDir = 'C:\7DaysToDieServer',
    [string]$SavesDir,
    [string]$ConfigFile,
    [string]$Region,
    [int]$LocalKeep = 3,
    [int]$S3KeepDays = 30,
    [int]$LogKeepDays = 30
)

# Beside the script unless the caller names one.
if (-not $ConfigFile) {
    $ConfigFile = Join-Path (Split-Path -Parent $MyInvocation.MyCommand.Path) 'backup-config.txt'
}

# Region only when asked for. Left out, the AWS Tools resolve it the way the
# CLI did: the profile's config, then AWS_REGION, then the SDK's default.
$aws = @{}
if ($Region) { $aws.Region = $Region }

$BackupDir = Join-Path $ServerDir 'backups'
$LogDir    = Join-Path $ServerDir 'backup-logs'
$Timestamp = Get-Date -Format 'yyyyMMdd-HHmmss'
$LogFile   = Join-Path $LogDir "backup-$Timestamp.log"
$Prefix    = '7days-backups/'
# Anchored, and [^/] so it cannot reach into a nested key: a listing is
# recursive where the CLI's `s3 ls` was not, and -like's * spans a slash.
$KeyPattern = '^' + [regex]::Escape($Prefix) + '7dtd-backup-[^/]+\.zip$'

foreach ($dir in $BackupDir, $LogDir) {
    if (-not (Test-Path $dir)) { New-Item -ItemType Directory -Path $dir | Out-Null }
}

function Write-Log {
    param([string]$Message = '')
    Add-Content -Path $LogFile -Value $Message -Encoding UTF8
    Write-Host $Message
}

function Stop-Run {
    param([string]$Message, [int]$Code = 1)
    Write-Log "ERROR: $Message"
    exit $Code
}

Write-Log '========================================'
Write-Log '7 Days to Die Server S3 Backup'
Write-Log "Started: $(Get-Date -Format 'ddd MM/dd/yyyy HH:mm:ss.ff')"
Write-Log '========================================'
Write-Log

# Which account ran matters more than anything else when credentials fail.
Write-Log ([Security.Principal.WindowsIdentity]::GetCurrent().Name)

if (-not (Test-Path $ConfigFile)) {
    Stop-Run "Config file not found at $ConfigFile. Write the bucket name on its first line"
}
$Bucket = "$(Get-Content $ConfigFile -First 1)".Trim()
if (-not $Bucket) { Stop-Run 'S3 bucket name not configured' }
Write-Log "S3 Bucket: $Bucket"
Write-Log

try {
    Import-Module AWS.Tools.S3, AWS.Tools.SecurityToken -ErrorAction Stop
} catch {
    Stop-Run "AWS Tools for PowerShell not available to this account: $($_.Exception.Message). Install AWS.Tools.S3 and AWS.Tools.SecurityToken with -Scope AllUsers"
}

Write-Log 'Testing AWS credentials...'
try {
    Get-STSCallerIdentity @aws -ErrorAction Stop | Out-Null
} catch {
    Stop-Run "AWS credentials or region not usable by this account: $($_.Exception.Message)"
}
Write-Log 'AWS credentials OK'
Write-Log

$BackupName = "7dtd-backup-$Timestamp.zip"
$BackupPath = Join-Path $BackupDir $BackupName
$Key        = "$Prefix$BackupName"
$Saves      = if ($SavesDir) { $SavesDir } else { Join-Path $ServerDir 'Saves' }
$Config     = Join-Path $ServerDir 'serverconfig.xml'

Write-Log 'Creating backup archive...'
Write-Log "Destination: $BackupPath"
Write-Log
if (-not (Test-Path $Saves)) {
    Stop-Run "Saves directory not found: $Saves"
}
Write-Log "Compressing: $Saves"
$sources = @($Saves, $Config)
try {
    Compress-Archive -Path $sources -DestinationPath $BackupPath -CompressionLevel Optimal -Force -ErrorAction Stop
} catch {
    Stop-Run "Failed to create backup archive: $($_.Exception.Message)"
}

$localSize = (Get-Item $BackupPath).Length
Write-Log "Backup created: $([math]::Round($localSize / 1MB)) MB"
Write-Log

Write-Log 'Uploading to S3...'
Write-Log "S3 path: s3://$Bucket/$Key"
try {
    Write-S3Object -BucketName $Bucket -Key $Key -File $BackupPath `
        -StorageClass STANDARD_IA @aws -ErrorAction Stop
} catch {
    Stop-Run "Failed to upload backup to S3: $($_.Exception.Message)"
}

# Read it back: the cmdlet returning is not the same as the bytes being there.
try {
    $remote = Get-S3Object -BucketName $Bucket -Key $Key @aws -ErrorAction Stop
} catch {
    Stop-Run "Upload returned but the object could not be read back: $($_.Exception.Message)"
}
if ($null -eq $remote) {
    Stop-Run "Upload returned but the object is not in the bucket: $Key"
}
if ($remote.Size -ne $localSize) {
    Stop-Run "Upload size mismatch: local $localSize bytes, S3 $($remote.Size) bytes"
}
Write-Log "Upload successful: $($remote.Size) bytes, $($remote.StorageClass)"
Write-Log

# From here the backup is in the bucket. A failure below is reported, not
# fatal: exit 2 says "backed up, but look at the log".
$pruneFailed = $false

Write-Log 'Cleaning up old local backups...'
Get-ChildItem $BackupDir -Filter '7dtd-backup-*.zip' |
    Sort-Object LastWriteTime -Descending |
    Select-Object -Skip $LocalKeep |
    ForEach-Object {
        $file = $_
        Write-Log "Deleting old backup: $($file.Name)"
        try {
            Remove-Item $file.FullName -ErrorAction Stop
        } catch {
            Write-Log "WARNING: could not delete $($file.Name): $($_.Exception.Message)"
            $pruneFailed = $true
        }
    }

Write-Log "Cleaning up old S3 backups (older than $S3KeepDays days)..."
# Both sides in UTC. LastModified's Kind isn't guaranteed, and comparing a
# local time against a UTC one shifts the retention boundary by the
# machine's offset.
$cutoff = [datetime]::UtcNow.AddDays(-$S3KeepDays)
try {
    $old = Get-S3Object -BucketName $Bucket -Prefix $Prefix @aws -ErrorAction Stop |
        Where-Object {
            $_.Key -match $KeyPattern -and
            $_.LastModified.ToUniversalTime() -lt $cutoff
        }
} catch {
    Write-Log "WARNING: could not list S3 backups: $($_.Exception.Message)"
    $pruneFailed = $true
    $old = @()
}
foreach ($object in $old) {
    Write-Log "Deleting old S3 backup: $($object.Key)"
    try {
        Remove-S3Object -BucketName $Bucket -Key $object.Key @aws -Force -ErrorAction Stop | Out-Null
    } catch {
        Write-Log "WARNING: could not delete $($object.Key): $($_.Exception.Message)"
        $pruneFailed = $true
    }
}

Get-ChildItem $LogDir -Filter 'backup-*.log' |
    Where-Object { $_.LastWriteTime -lt (Get-Date).AddDays(-$LogKeepDays) -and $_.FullName -ne $LogFile } |
    Remove-Item -ErrorAction SilentlyContinue

Write-Log
Write-Log '========================================'
if ($pruneFailed) {
    Write-Log "Backup completed with warnings: $(Get-Date -Format 'ddd MM/dd/yyyy HH:mm:ss.ff')"
    Write-Log '========================================'
    exit 2
}
Write-Log "Backup completed: $(Get-Date -Format 'ddd MM/dd/yyyy HH:mm:ss.ff')"
Write-Log '========================================'
exit 0

A few lines look odd until you know why they are there:

• The log function uses Write-Host, not Write-Output, so log lines do not leak into whatever the script returns.
• After the upload, the script fetches the object’s details and compares its size with the local file. That confirms an object with that key is in the bucket. The upload cmdlet returning without an error does not prove that on its own. It checks length, not content; S3 already verifies the transfer’s checksum.

5. Register the task

From an elevated PowerShell:

Unblock-File C:\Scripts\backup-s3.ps1

$action = New-ScheduledTaskAction -Execute 'powershell.exe' `
    -Argument '-NoProfile -ExecutionPolicy RemoteSigned -File "C:\Scripts\backup-s3.ps1"'
$trigger = New-ScheduledTaskTrigger -Daily -At 11:00
Register-ScheduledTask -TaskName '7DaysToDieServerS3Backup' `
    -Action $action -Trigger $trigger -User 'SYSTEM' -RunLevel Highest

A script that arrives by download or inside a zip carries the mark of the web. RemoteSigned refuses to run it until Unblock-File clears the mark. Bypass would also work, but it would hide the next blocked file too. Steps 1 and 2 exist because of -User 'SYSTEM'. The VM’s clock is UTC, so 11:00 is early morning Pacific, ahead of the server’s own update window. Pick an hour when nobody is playing.

Start the first run from the scheduler, not by hand. A run from your own session uses your credentials, so it tests the script but not the task:

Start-ScheduledTask 7DaysToDieServerS3Backup
Start-Sleep 30
(Get-ScheduledTask 7DaysToDieServerS3Backup | Get-ScheduledTaskInfo).LastTaskResult

0, and a new log under C:\7DaysToDieServer\backup-logs whose identity line reads NT AUTHORITY\SYSTEM.

Expected result

Each run writes one log. This one is from a morning when both prunes had work to do: a fourth archive had built up on disk, and one in the bucket had reached thirty days.

========================================
7 Days to Die Server S3 Backup
Started: Fri 09/25/2026 14:28:39.98
========================================

NT AUTHORITY\SYSTEM
S3 Bucket: 7dtd-server-backups

Testing AWS credentials...
AWS credentials OK

Creating backup archive...
Destination: C:\7DaysToDieServer\backups\7dtd-backup-20260925-142839.zip

Compressing: C:\7DaysToDieServer\Saves
Backup created: 23 MB

Uploading to S3...
S3 path: s3://7dtd-server-backups/7days-backups/7dtd-backup-20260925-142839.zip
Upload successful: 23917749 bytes, STANDARD_IA

Cleaning up old local backups...
Deleting old backup: 7dtd-backup-20260924-145409.zip
Cleaning up old S3 backups (older than 30 days)...
Deleting old S3 backup: 7days-backups/7dtd-backup-20260826-110000.zip

========================================
Backup completed: Fri 09/25/2026 14:28:45.92
========================================

That’s six seconds, start to finish. The account name near the top is there because when a run fails on credentials, the first thing to find out is which account ran it.

To list what’s in the bucket:

Get-S3Object -BucketName 7dtd-server-backups -Prefix 7days-backups/ |
    Select-Object Key, Size, LastModified

Expect one archive for each morning the machine was on, and about thirty days of them.

Restore a backup

Each archive is a plain zip holding Saves and serverconfig.xml, so a restore is a download and an Expand-Archive. Run this in your own session if its credentials can read the bucket, and you want to be watching. The backup user’s credentials in SYSTEM’s profile can read it too, so a scheduled task that runs as SYSTEM can do the download on a machine that has only those.

1. Stop the server.

2. Move the current saves out of the way, so the restored tree stands alone and the old one is still there if you need it:

   PowerShell

   $saves = 'C:\7DaysToDieServer\Saves'   # or the path you passed as -SavesDir
   Rename-Item $saves Saves.before-restore

3. Download the archive you want and expand it into a temporary directory:

   PowerShell

   $name = '7dtd-backup-20260925-142839.zip'
   $zip  = Join-Path $env:TEMP $name
   $dir  = Join-Path $env:TEMP '7dtd-restore'
   Read-S3Object -BucketName 7dtd-server-backups -Key "7days-backups/$name" -File $zip
   Expand-Archive $zip -DestinationPath $dir -Force

4. Move Saves into place:

   PowerShell

   Move-Item (Join-Path $dir 'Saves') $saves

5. Only if you want the old settings back, copy the old serverconfig.xml over the current one:

   PowerShell

   Copy-Item (Join-Path $dir 'serverconfig.xml') C:\7DaysToDieServer\ -Force

6. Start the server.

Do a practice restore on a scratch machine before you need one for real. Until you’ve done that, you don’t know that the backup works.

Use a different destination

S3 appears in steps 1 to 3, the script’s setup checks, its upload and its S3 prune. Everything else works with any destination. To write to another drive or a share instead:

• Skip steps 1 to 3. In the script, delete everything between the line that logs the account name and $BackupName: the backup-config.txt check, the module import and the credentials test. Left in, the missing config file stops every run before the copy.

• Replace everything from Uploading to S3... through Upload successful with a copy, checked the same way:

  PowerShell

  $Destination = '\\nas\backups\7dtd'
  try {
      Copy-Item $BackupPath -Destination $Destination -ErrorAction Stop
      $remote = Get-Item (Join-Path $Destination $BackupName) -ErrorAction Stop
  } catch {
      Stop-Run "Failed to copy backup to ${Destination}: $($_.Exception.Message)"
  }
  if ($remote.Length -ne $localSize) {
      Stop-Run "Copy size mismatch: local $localSize bytes, destination $($remote.Length) bytes"
  }
  Write-Log "Copy successful: $($remote.Length) bytes"

• Replace the S3 prune with a date-based Get-ChildItem prune on the destination, like the one the script uses for its log files.

A share needs one more decision, because the task runs as SYSTEM. On a domain, SYSTEM reaches the network as the computer account (SERVER$), so grant that account write access on the share. Outside a domain, SYSTEM has no identity a NAS will accept. Run the task as a local user that can write to the share instead.

A second disk in the same machine protects you from a failed drive. It doesn’t help if you lose the whole machine.

Why it is built this way

A zip a day, not a sync. A sync keeps one current copy of each file, so a save that corrupts on Tuesday overwrites Monday’s good copy on Tuesday night. A dated zip each day gives you thirty separate restore points without setting up versioning. At 23 MB a day, a whole month is under a gigabyte.

STANDARD_IA, because the retention matches. Infrequent Access charges for at least 30 days of storage per object. Objects pruned at exactly 30 days pay that minimum and nothing more, at a lower per-gigabyte rate than Standard. A restore reads one object once, so the retrieval charge stays small.

Retention in two places. The script prunes the bucket at 30 days, and so does the lifecycle rule. On 2026-09-10 the VM was switched off, and it stayed off for twelve days. The script didn’t run, so its prune didn’t either, but the lifecycle rule kept deleting. When the machine came back, the bucket held only the archives from the last thirty days, about twelve short of thirty. If retention lived only in the script, old archives would pile up whenever the script stopped running.

Three exit codes, not two. Once the upload succeeds, the backup exists, and a later failure shouldn’t be reported the same way as an earlier one. Exit 2 means “backed up, check the log”. Task Scheduler still shows it as a non-zero result, so you notice it.

What the batch file it replaced got wrong

A batch file, backup-s3.bat, did this job from 2026-02-06 to 2026-09-22. It called PowerShell only for Compress-Archive and a date comparison, and it never missed a morning the machine was on. If you run something like it, it probably has the same three defects:

set TIMESTAMP=%date:~-4,4%%date:~-10,2%%date:~-7,2%-%time:~0,2%%time:~3,2%%time:~6,2%

• The timestamp cut %date% up by character position. That only works with the en-US format, Tue 09/22/2026. With any other system locale, the filenames come out scrambled.
• The S3 prune ran aws s3 rm in a loop without checking any results, and the file always ended with exit /b 0. If the s3:DeleteObject permission had been missing, nobody would have noticed, because the lifecycle rule would have done the deleting instead.
• Each log carried ninety lines of the CLI’s progress bar around the one line that mattered.

None of the three ever caused a failure. The AWS CLI went too, the day after the switch. aws s3 cp reports failure only through an exit code, which has to be checked after every call. A script that misses one check reports success for an upload that didn’t happen. Write-S3Object throws an error instead, and one try/catch handles it.

Common failures

AWS Tools for PowerShell not available, but the module imports fine for you

The modules were installed per-user instead of with -Scope AllUsers, so they’re under your Documents folder, where SYSTEM can’t see them. Get-Module -ListAvailable AWS.Tools.S3 shows the path.

AWS credentials or region not usable by this account, but the same call works for you

The task isn’t running as you, so it doesn’t use your credentials. Go back to step 2. The account name at the top of the log shows who ran it. The message mentions the region because a missing region fails at the same point as a missing key. It’s easy to spend an hour in the credentials file when the problem is in config.

Task arguments come out mangled

On this server, schtasks /Change /TR with a quoted path inside the string produced -File " C:\Scripts\backup-s3.ps1\, with a leading space and a stray backslash. New-ScheduledTaskAction sets Execute and Arguments as separate values, so the quoting survives. Use Set-ScheduledTask -Action to apply it to an existing task.

After an outage, the result reads The operator or administrator has refused the request

The machine was off at 11:00. On boot, the scheduler recorded event 153, “Missed task start rejected”, because the task’s “run as soon as possible after a scheduled start is missed” setting is off. Nothing failed, and the next 11:00 run goes ahead normally. Turn the setting on if you want a catch-up run, at the cost of a backup taken while the server is still starting.

Compress-Archive fails on one large file

Compress-Archive can’t add a single file over 2 GB. The limit comes from the .NET API underneath it, in both Windows PowerShell 5.1 and PowerShell 7. Nothing under Saves comes near that on this server. If one of your files does, use tar.exe, which ships with Windows Server 2019 and later and has no such limit.

Saves are captured mid-write

The server keeps running and writing while the archive is taken, so a restored save can be a few minutes stale. If that matters for your world, stop the server before the backup, or accept the gap.

TL;DR

# Install once per machine; later sessions only need Import-Module.
Install-Module -Name AWS.Tools.CloudWatch -Scope CurrentUser -Force
Import-Module AWS.Tools.CloudWatch

$datum = New-Object Amazon.CloudWatch.Model.MetricDatum
$datum.MetricName = 'QueueDepth'
$datum.Value      = 42
$datum.Unit       = 'Count'
$datum.Timestamp  = (Get-Date).ToUniversalTime()

$hostDimension = New-Object Amazon.CloudWatch.Model.Dimension
$hostDimension.Name  = 'Host'
$hostDimension.Value = [Environment]::MachineName
$datum.Dimensions = @($hostDimension)

Write-CWMetricData -Namespace 'MyApp/Queue' -MetricData $datum

The metric appears under Metrics > All metrics > MyApp/Queue in the CloudWatch console once CloudWatch has indexed it, which can take some minutes. The namespace is yours to choose; don’t begin it with AWS/, which AWS services use.

A custom metric is any number you care about, sent to CloudWatch so you can graph it and alarm on it like a built-in metric: a queue depth, the number of files waiting in a drop folder, or the age of the newest backup. In PowerShell, you put the number in a MetricDatum object and pass it to Write-CWMetricData.

Install the CloudWatch module

AWS.Tools ships one module per AWS service, so you install only the CloudWatch one. It pulls in AWS.Tools.Common on its own:

Install-Module -Name AWS.Tools.CloudWatch -Scope CurrentUser -Force
Import-Module AWS.Tools.CloudWatch

When installing from PSGallery, -Force skips the “Untrusted repository” prompt.

The AWS Tools look for credentials in a profile, in environment variables, or in the instance’s role when the script runs on EC2. Whichever identity they find needs permission for cloudwatch:PutMetricData, the API call behind Write-CWMetricData. CloudWatch is regional, so the tools also need a region: from the profile, the AWS_REGION environment variable, Set-DefaultAWSRegion, or -Region on the cmdlet itself.

Build the MetricDatum

A MetricDatum holds one data point. MetricName names it and Value is the number; Unit and Timestamp are optional but worth setting:

$datum = New-Object Amazon.CloudWatch.Model.MetricDatum
$datum.MetricName = 'QueueDepth'
$datum.Value      = 42
$datum.Unit       = 'Count'
$datum.Timestamp  = (Get-Date).ToUniversalTime()

Unit takes one of a fixed list of names, such as Count, Seconds, Bytes or Percent; MetricDatum in the CloudWatch API Reference (opens in a new tab) lists them all. PowerShell doesn’t check the name when you assign it, so a misspelled unit fails only when Write-CWMetricData sends it. Pick the unit the number actually is. CloudWatch never converts between units, and a metric sent as Count one day and None the next becomes two separate series.

Leave Timestamp off and CloudWatch uses the time the data arrives. Set it when you measured the number earlier than you send it.

Add a dimension

A dimension is a name and a value that describe where the number came from. Without one, every host that sends QueueDepth adds to the same series. With a Host dimension, each host gets its own series. CloudWatch doesn’t add those series together for you; to see all hosts at once, sum them with metric math, or send each datum a second time without the dimension.

$hostDimension = New-Object Amazon.CloudWatch.Model.Dimension
$hostDimension.Name  = 'Host'
$hostDimension.Value = [Environment]::MachineName
$datum.Dimensions = @($hostDimension)

Use [Environment]::MachineName rather than $env:COMPUTERNAME, which is set only on Windows. On macOS or Linux it’s empty, and CloudWatch rejects an empty dimension value.

Keep dimensions few. CloudWatch bills each distinct combination of dimension values as its own metric. A dimension whose value changes every time, such as a request ID or a timestamp, creates a new metric on every run. CloudWatch pricing (opens in a new tab) shows what each custom metric costs.

Send it with Write-CWMetricData

Write-CWMetricData -Namespace 'MyApp/Queue' -MetricData $datum

-MetricData takes an array, so a script that measures several things can send them in one call:

Write-CWMetricData -Namespace 'MyApp/Queue' -MetricData @($depth, $oldestAge, $workers)

One call can carry only so many data points and dimensions; PutMetricData in the CloudWatch API Reference (opens in a new tab) has the current limits.

The cmdlet prints nothing when it succeeds and throws an error when it fails. In a script that runs unattended, wrap it in try/catch; otherwise the script carries on as if the number had been recorded.

Expected result

In the CloudWatch console, open Metrics > All metrics. The MyApp/Queue namespace is listed, and inside it a Host group with one row for each host that has sent data. To check from PowerShell instead:

Get-CWMetricList -Namespace 'MyApp/Queue' | Select-Object MetricName, Dimensions

A new metric can take a few minutes to appear in that list while CloudWatch indexes it; the data was still received. Get-CWMetricData can read the data points before the metric is listed.

Why this works

Write-CWMetricData calls the CloudWatch PutMetricData API. CloudWatch files each data point under its namespace, metric name and set of dimensions, and those three together identify one series.

Standard metrics are stored at one-minute resolution. A number sent once a minute comes back as that number. Numbers sent more often, say every five seconds, are combined into that minute’s sum, count, minimum and maximum. To keep them separate, set StorageResolution to 1 for a high-resolution metric. That costs the same per metric as a standard one; what costs more is the extra calls and any alarm that checks more often than once a minute.

Common failures

Import-Module can’t find AWS.Tools.CloudWatch

Import-Module: The specified module 'AWS.Tools.CloudWatch' was not loaded because no valid module file was found in any module directory.

The CloudWatch module isn’t installed for your account. Installing AWS.Tools.Installer doesn’t install it:

Install-Module -Name AWS.Tools.CloudWatch -Scope CurrentUser -Force

New-Object can’t find the MetricDatum type

New-Object: Cannot find type [Amazon.CloudWatch.Model.MetricDatum]: verify that the assembly containing this type is loaded.
InvalidOperation: The property 'MetricName' cannot be found on this object. Verify that the property exists and can be set.

The module is installed but hasn’t been imported yet. PowerShell imports a module on its own when you call one of its cmdlets, but not when you use one of its types, and New-Object comes first. Every property error after it has the same cause: $datum is empty. Import the module before anything else:

Import-Module AWS.Tools.CloudWatch

Write-CWMetricData prints nothing

No output means it worked. The cmdlet has no output on success and throws an error on failure.

Metric not showing up

Give it a few minutes. A new metric takes a while to appear in the list, and a data point with a timestamp in the past takes longer still. CloudWatch also accepts timestamps only within a window around the current time. PutMetricData in the CloudWatch API Reference (opens in a new tab) gives the current delays and the window.

Graph not updating, or flat at the wrong value

The console graphs the Average over a period longer than a minute. A metric sent once a minute shows the average of several values, so one new value barely moves the line. Set the period to one minute, or switch the statistic to Maximum or Sum, whichever is the number you want.

Namespace keeps filling with new metrics

A dimension value changes on every run. Look at the dimension values under the namespace: if the list grows with each run, that dimension is an identifier, not a category. Put it in a log line instead.

No credentials

Failed to resolve AWS credentials. The credential providers used to search for credentials returned the following errors:

PowerShell found no profile, environment variables or instance role, so the call never reached CloudWatch. Choose a profile for the session, or set the AWS_PROFILE environment variable:

Set-AWSCredential -ProfileName <name>

No region

No region specified or obtained from persisted/shell defaults.

The credentials were found but no region was. Set one for the session, set AWS_REGION, or add -Region <region> to Write-CWMetricData:

Set-DefaultAWSRegion -Region <region>

Not authorized to call PutMetricData

Write-CWMetricData: User: arn:aws:sts::<account-id>:assumed-role/<role>/<session> is not authorized to perform: cloudwatch:PutMetricData because no identity-based policy allows the cloudwatch:PutMetricData action

The credentials work, but the identity named in the message isn’t allowed to call cloudwatch:PutMetricData. To see that identity, install the AWS.Tools.SecurityToken module the same way as the CloudWatch one and run:

Get-STSCallerIdentity