Primer on Creating Scheduled Tasks via PowerShell
I, too, was trying to create a scheduled task on Windows Server 2019 using PowerShell. None of the answers worked. It seems like all the answers really have bits and pieces of the correct solution, but none had the full solution. While some of the answers may have worked for some people, it was really all luck based on their existing system, security settings, and other factors, I'm sure. There's a lot that I learned on my journey to creating a really simple scheduled task via PowerShell to collect some application telemetry.
So I've completely revised my original answer and will now take you step-by-step through what it takes, in nearly all circumstances, to create a Scheduled Task, especially on a server. If only it were as simple as cron.
Assigning Logon as a batch job for users running unattended tasks
When most people want to create a scheduled task, especially for server/application maintenance, or just to run something on a periodic basis, the first stop is the Windows Task Scheduler. A nice GUI is provided (well, it could be nicer/modernized, but hey, at least it's a GUI) where you can specify all the details necessary to get you going. The problem is, you can't automate the GUI. And as I found out, the GUI is doing things behind the scenes that Microsoft isn't exactly forthright in telling you how it's doing it (or how it's not doing it, for that matter). And that can lead to a lot of issues—including the task just not running or even the user account under which the task runs becoming locked.
In Microsoft's documentation on the Logon as a batch job (SeBatchLogonRight) under the Group Policy heading, Microsoft states that, "Task Scheduler automatically grants this right when a user schedules a task." Well, this statement is not always true.
When you create a scheduled task using the Task Scheduler GUI, yes, if the scheduled task is configured to Run whether the user is logged on or not and the user does not have the Logon as a batch job right, then the Task Scheduler will assign that right to the user (unless that default is changed—see the referenced link above).
However, when creating a scheduled task using the PowerShell ScheduledTask module's cmdlets, this automatic user rights assignment DOES NOT occur. So you must do this manually. The GUI way to do this is to use the Local Security Policy MMC (Microsoft Management Console). Of course, the GUI is out in an automation scenario, so your friend here will be secedit.exe. (For myself, I wrote PowerShell wrappers around secedit.exe.)
So, let's assume we have a scheduled task that will collect telemetry for an application running on your server, which will then send that telemetry to your telemetry gathering service, such as New Relic or Data Dog, for example. The task will run under the user account CONTOSO\AppTelemetry. Given we'll be creating the scheduled task via PowerShell in an automated fashion during blue/green deployments, we need to assign this user the Logon as a batch job user right.
Using secedit to assign user rights
The steps are quite simple here:
- Export the existing server's security policy to a security policy template (optionally, only containing the sections you care about)
- Create a new security policy template
- Add the security identifier (SID) of the user under which the scheduled task will run to the corresponding user right in the new security policy template
- Import the security policy template containing the security policy changes to a new database
- Configure the system's security policy to incorporate the changes in the security policy database created in step 4.
Let's go through the code that will make this happen.
Export the existing server's security policy to a security policy template
You can do this from CMD or from PowerShell (Desktop edition or Core, it doesn't matter). All examples will be in PowerShell unless noted otherwise.
secedit.exe /export /cfg secpol.inf /areas USER_RIGHTS
The above command exports the system's security policy, but only the section that contains information on User Rights assignments. If you need to add additional settings, such as registry keys, this can also be done via security policy. Read the Microsoft documentation on secedit.exe or Security Policies, in general.
Create a new security policy template and add our scheduled task user's SID to the SeBatchLogonRight value
Now we need to make a new security policy template that contains the delta of what we want to be the new security policy vs. what is the current security policy. I recommend that the new security policy template contain as little information as possible—only those settings which need to be changed.
One would think that all you need to do is specify that the SeBatchLogonRight must include the SID for the user, and that would be it. But if you thought that, you'd be wrong. The SeBatchLogonRight has some users assigned to it by default (see the above-referenced link to the Microsoft docs). If we were to just assign our user's SID to this right in the new policy template, it would effectively replace the existing value in the system's security policy, not update it. So since we're making an additive change, we need to add this user right to our template with the existing value from the system security policy that we exported above, and then add our user SID to the list.
By default, the SeBatchLogonRight has these SIDs assigned to it:
SeBatchLogonRight = *S-1-5-32-544,*S-1-5-32-551,*S-1-5-32-559,*S-1-5-32-568
These are some "well-known" SIDs for some standard Windows security groups whose users should have this right. Let's assume the SID for CONTOSO\AppTelemetry is S-1-5-21-0000000000-1111111111-2222222222-3333. But wait—how do you get that?
function ConvertTo-SecurityIdentifier {
Param (
[Parameter(Position = 0, Mandatory, ValueFromPipeline)]
[string[]] $UsernameOrGroup
)
Process {
foreach ($Name in $UsernameOrGroup) {
$Account = New-Object -Type System.Security.Principal.NTAccount `
-Argument $Name
$Account.Translate([System.Security.Principal.SecurityIdentifier]).Value
}
}
}
Set-Alias -Name ConvertTo-SID -Value ConvertTo-SecurityIdentifier
function ConvertFrom-SecurityIdentifier {
Param (
[Parameter(Position = 0, Mandatory, ValueFromPipeline)]
[string[]] $SecurityIdentifier
)
Process {
foreach ($SID in $SecurityIdentifier) {
$Account = New-Object -Type System.Security.Principal.SecurityIdentifier `
-ArgumentList $SID
$Account.Translate([System.Security.Principal.NTAccount]).Value
}
}
}
Set-Alias -Name ConvertFrom-SID -Value ConvertFrom-SecurityIdentifier
(Why didn't I simply use Get-ADUser to get the SID for a user account? Two reasons. First, it's not as straightforward to get a user account name from a SID using Get-ADUser. It can be done, but the code above is clearer. Secondly, and most importantly, not all users will have Get-ADUser installed on their machines. My previous laptop had the Windows Remote Server Administration Tools (RSAT) installed, so I had Get-ADUser available. Without RSAT installed or installing the Active Directory PowerShell module, Get-ADUser is not available. The cmdlets above work without a dependency on anything except Windows and the .NET framework, which, if you're trying to get a user account SID and using PowerShell to do so, by definition, you most likely have the two prerequisites.)
Then you can simply run:
$SID = 'CONTOSO\AppTelemtry' | ConvertTo-SecurityIdentifier
Now that we have our SID, we can create a security policy template (note, there are better ways to do this—I created PowerShell cmdlets that let me programmatically interact with these INF files, but I'm just going to use here documents). Note that in the security policy you exported, all SIDs are prefixed with an *, and that multiple values are comma-delimited:
$NewPolicy = @'
[Unicode]
Unicode=yes
[Version]
signature="$CHICAGO$"
Revision=1
[Privilege Rights]
SeBatchLogonRight = *S-1-5-32-544,*S-1-5-32-551,*S-1-5-32-559,*S-1-5-32-568,*S-1-5-21-0000000000-1111111111-2222222222-3333
'@
$NewPolicy | Set-Content batchlogon.inf
Import the new security policy template to a new security policy database
The heading says it all:
secedit.exe /import /db batchlogon.sdb /cfg batchlogon.inf
Configure the system security policy with the changes contained in the new security policy database
Once again, the heading says it all:
secedit.exe /configure /db batchlogon.sdb
And that's all there is to add a user to the Logon as a batch job right from the CLI.
Create a Scheduled Task via PowerShell
Now that the user has the right to run the scheduled task whether or not they are logged in, we need to create a scheduled task that will run whether or not the user is logged in. You will see many links to many Q&A answers that say you need this or that LogonType (notably, S4U or ServiceAccount) or run it with the highest privileges, etc. Don't listen to any of that. It's (mostly) wrong. This section will outline the minimum necessary steps to achieve creating a scheduled task that runs whether the user is logged on or not.
Create the Scheduled Task Action
First up is creating the task action. Scheduled tasks are made up of a few parts:
- Actions
- Triggers
- Settings
- Principal(s)
- Registration
The names are fairly self-explanatory. We'll be creating a scheduled task action that executes a program. (There are other action types. See the documentation on Task Actions.)
The important thing to know about Exec actions is that the Task Scheduler service will spawn an instance of cmd.exe to run the provided program. This means that if you need to specify arguments to the program, you need to ensure you follow the difficult quoting rules for CMD commands. (Depending on your arguments, these quoting rules can require a lot of testing to ensure the command will run as expected. In even my simple case, I got it wrong, and the task seemed to run correctly—a 0 exit code—but did nothing at all!) See cmd.exe /? for all the gory details. Also, you can find a lot of info through a web search.
Let's create the task action:
$TaskAction = New-ScheduledTaskAction -Execute 'powershell.exe' `
-Argument ('-NoLogo -ExecutionPolicy Bypass -NoProfile -NonInteractive' + `
'-File "C:\Telemetry\Send-ApplicationTelemetry.ps1"')
Again, be careful of quoting rules (i.e. if your file path has spaces in it, or, in the case you pass a bit of PowerShell script to the -Command parameter as opposed to using -File as I did here). There are a few things to point out here:
- I could've used
pwsh.exe instead to run PowerShell Core
-NoLogo avoids printing the "banner" that appears when you start PowerShell. It can make redirected output to log files nicer if you do such a thing.-ExecutionPolicy Bypass specifies that this script will bypass any current execution policy on the system. The default execution policy is Restricted, which disallows any script from running unless a full path is specified, and disallows any scripts which came from remote sources. This switch basically ensures that the script will be run. It may not always be necessary, but if you trust the script you're scheduling, this shouldn't hurt either.-NoProfile is used to not load the user's PowerShell profile (it's a similar concept to a user's bash profile on Linux OSes). However, there can also be global profile scripts. Unless you know you need profile scripts to run when PowerShell starts, it doesn't hurt to add this switch, and most likely will prevent errors.-NonInteractive is a very important switch. Basically, this prevents Powershell from prompting for user input (e.g. for cmdlets that require confirmation or user input). This also means if your script does require confirmation/user input, it won't work non-interactively (i.e. when the user is not logged on).-File tells PowerShell to execute the specified file. You could also use -Command instead and pass in some "stringified" PowerShell code.
Create the Scheduled Task Principal
This is the most important step for properly creating a scheduled task that will run whether the user is logged in or not. In fact, this step is REQUIRED to configure a scheduled task to Run whether the user is logged on or not.
$TaskPrincipal = New-ScheduledTaskPrincipal -Id 'Author' `
-UserId 'CONTOSO\AppTelemetry' `
-LogonType Password `
-RunLevel Limited
Let's go over these settings in a bit more detail.
-Id
This is a free-form text field, so much as I can tell. The Task Scheduler GUI always uses the term 'Author', but generally, you can use whatever you want here. The caveat though, is that a scheduled task can contain many different actions (up to 32). And Actions also have a "context" associated with them. The task scheduler automatically assigns the context to 'Author' (for simple, single-action tasks). The documentation seems to indicate that you can provide more than one principal to a scheduled task, and the Id of the principal, in correlation with an action's context, will determine under which principal an action will execute. For our single-action task, we'll just go with 'Author'.
-UserId or -GroupId
A task can run under a user account or any user belonging to a specified Group. Be aware that when using a group, only when a user of the group is logged on will the scheduled task run. That's because using a group ID, you cannot specify a password for the task.
In 99% of the cases, you're going to want to use -UserId as I did above. It doesn't need to be a fully qualified user Id. Note that we don't store the password with the principal. That comes later.
-LogonType
This is probably one of the most misunderstood parameters of this cmdlet. The documentation on LogonType is pretty good. Too bad the PowerShell help for New-ScheduledTaskPrincipal doesn't link to it (I put in feedback about that).
Basically, you'll probably never need to be concerned with the S4U logon type. It may be relevant in some scenarios (which is why it exists), but for almost everything, you'll want to do, it probably won't be.
You'll only use the ServiceAccount logon type if the scheduled task will run under the NT AUTHORITY\LOCALSYSTEM, NT AUTHORITY\SYSTEM user accounts, for example. (There's a third one, but the name escapes me at the moment.) Since our task is not running under a system account, this is not the value we want.
As you might be able to guess, Interactive means the task will be run under the context of a logged-on user. This can be useful when the task needs to start a GUI application, or the task action is Message Box to display a dialog on the system. Obviously, this is not useful in our case. There's also the InteractiveOrPassword type which combines this logon type, with the one we want, Password. And so I won't discuss it further.
And now, of course, the Password logon type, which is the one we want. This says that a password will be stored with the scheduled task, which will be used to logon the user (as a batch job) so the task can run whether the user is logged on or not. Yes, this is the value that results in setting the Run whether the user is logged on or not checkbox in the Task Scheduler UI.
-RunLevel
Think of this option as specifying whether or not the task needs to run with elevated privileges. When you run a command, such as installing some software, the User Access Control (UAC) kicks in and displays a dialog asking if you want to allow the program to make changes to your computer. You probably click Yes half the time without even reading it. Setting this parameter to Highest is like clicking Yes to the UAC dialog (or just starting the process with elevated privileges, i.e. Run as Administrator). This is a bad thing, unless you know you need it. You should always start with Limited, and if you find the scheduled task won't run under those privileges, then elevate. So that's what I've done. I'm starting with the principle of least privilege and using Limited run level.
Creating the Scheduled Task trigger
You can have one or more triggers to trigger a scheduled task. There are different trigger types. See the documentation for these different types. I'm just going to do a very simple one:
$TaskTrigger = New-ScheduledTaskTrigger -Once -At ([DateTime]::Now.AddMinutes(5)) `
-RepetitionInterval ( `
[TimeSpan]::FromMinutes(5) `
)
I just want a task that will run once, starting 5 minutes from now, and then run subsequently every 5 minutes after that.
Task Settings Set
If I needed to customize some other task settings, I could do so by using New-ScheduledTaskSettingsSet. I'm fine with the defaults, so I'll skip this. But the Task Scheduler documentation details it all, and really, the settings are quite self-explanatory for the most part (except the RunOnlyIfNetworkIsAvailable, but it's not overly difficult to understand).
Create the Scheduled Task
Now you might think this is where we create the task and we'll get to see it in Task Scheduler. Wrong. But we will be creating a Scheduled Task object. You MUST do this step or your task will not be registered correctly—most importantly, it will not be set up to Run whether the user is logged in or not.
$Task = New-ScheduledTask -Description 'Collects application telemetry' `
-Action $TaskAction `
-Principal $TaskPrincipal `
-Trigger $TaskTrigger
All that's happening here is we're creating a scheduled task instance. But it has not been added to the list of tasks in the task scheduler. That's known as registration, and we'll be doing that next. If you just type $Task in your shell after executing the above command, you'll notice that the task name and path will be blank. You can't even specify it as part of calling New-ScheduledTask. Again, that, oddly enough, happens during registration. So let's talk about the second-most important part: registration.
Registering the Scheduled Task
It is true that I could simply:
$Task = Register-ScheduledTask -TaskName 'Foo' -TaskPath `\` `
-Action $TaskAction -Trigger $TaskTrigger `
-User 'SomeUser' -Password '$uper53cr37'
But this would result in a task that runs interactively (Run only when the user is logged on). And this is not what we want. This is why we created the task principal above, and a task instance containing the task principal.
So let's register our task:
$Task = $Task | Register-ScheduledTask -TaskName 'Collect Telemetry' `
-TaskPath '\Awesome App' `
-User 'CONTOSO\AppTelemetry' `
-Password 'ShhD0ntT3ll4ny0n3!'
So as you can see, yes, you MUST supply a password. There are various ways to do this safely and securely in an automated fashion—but alas, not so easy for demonstration purposes. (I recently came across this blog post: How to use the Secret Modules which outlines yet another tool in your PowerShell secrets management arsenal.) The important part here is the user and password provided to Register-ScheduledTask. The specified user MUST be the same user as specified in the principal we created. And obviously, the password for that user must be correct. IF you use a different user to register the scheduled task, the task principal will be updated to run the task using the user account specified when registering the task. (That's documented here.)
And that's all there is to scheduling a task to run whether the user is logged on or not using PowerShell. But there's one more topic to discuss before I finish: updating a scheduled task.
Updating a Scheduled Task
Believe it or not, this is not as straightforward as it should be. The syntax for Set-ScheduledTask is not documented correctly. Let's pretend that I need wo write a file somewhere as part of this scheduled task, but the code that writes the file doesn't use an absolute path. Therefore, I need to set a working directory and forgot to do so. Let's fix the action and update the task.
This is the way to do it properly. There are different ways you can use Set-ScheduledTask, but I found that other ways of doing it can lock the user account or just plain not work (i.e. give you an error). It's not to say those other ways are wrong, but just for this particular kind of change, this is what worked for me every time:
$Task = Get-ScheduledTask -TaskName 'Collect Telemetry' -TaskPath '\Awesome App'
$Task.Actions[0].WorkingDirectory = 'C:\AwesomeApp'
$Task | Set-ScheduledTask -User 'CONTOSO\AppTelemetry' -Password 'ShhD0ntT3ll4ny0n3!'
Again, it's important to use the same user and password used when registering the task. If you use a different username/password, then the task principal WILL ALSO be updated. That's probably not what you want.
That's pretty much all there is to working with Scheduled Tasks in Powershell.
Use schtasks for debugging help
One way to help yourself when you're having trouble creating scheduled tasks via PowerShell is to create a similar scheduled task on your local computer via the GUI. Then you can use the schtasks command to query for the scheduled task you created via the GUI and compare it with the scheduled task you created via PowerShell. To use schtasks, for example:
# To get the XML for the task:
schtasks /query /tn '\My Task Path\MyTask' /xml ONE
# To get a nice formatted list of the task properties:
schtasks /query /tn '\My Task Path\MyTask' /v /fo LIST
You can also get a scheduled task's XML representation via PowerShell using Export-ScheduledTask. You can find documentation for all of the PowerShell Scheduled Task cmdlets here. The documentation is OK. Some of it is misleading; most of it is incomplete (i.e. it assumes you have knowledge about the Task Scheduler apart from the PowerShell cmdlets themselves). Documentation on the Task Scheduler, its COM interfaces, XML schema, etc., can be found here.
Conclusion
I hope this helps someone because it took me a long time to figure this all out. Mainly, a lot of, "Why isn't this task doing anything even when it says it's successful?" Or "Why does the account keep getting locked out?" (Wrong logon type, password, or user rights assignment, or all 3!)
