Table of Contents

Deployment Node

The Deployment Node is an optional program for networks with strict rules. Use it when remote PowerShell or WMI is blocked, but a workflow still needs to run a script on another server.

You install the Node on that other server. The SharpDay Deploy server connects to it with Kerberos or NTLM, and asks it to run a script.

The Node only runs scripts that are already in its own Scripts folder. Nobody can send it new commands or scripts.

In a workflow, use the Run SDDN Command step to call it. You find it in the Extras group of the workflow editor, when the workflow runs on the server.

What you need

  • A Windows domain.
  • Windows Server 2019 or newer, or Windows 11 version 22H2 or newer. It must be 64-bit.

You do not need to install .NET or anything else first. The Node is free, and needs no licence of its own.

Get the installer

Sign in at www.sharp.day and open Downloads. SharpDay Deployment Node is listed below SharpDay Deploy, for accounts with a SharpDay Deploy licence. Select Download .msi.

The Node has its own version numbers. View changelog on the Downloads page shows what changed in each version.

Install it

1. Run the installer

Run SharpDayDeploymentNode-<version>.msi on the server that will run the scripts. The installer asks you to accept the licence agreement. You can run it by hand or push it out with your usual tools:

msiexec /i SharpDayDeploymentNode-1.0.0.0.msi /qn /l*v install.log

The installer adds a Windows service called SharpDay Deployment Node (service name SharpDayDeploymentNode). It runs as Local System. If you want to use Kerberos with a managed account, read Set up Kerberos before you change this.

The service does not start until the server restarts. To start it now, open Services and start SharpDay Deployment Node, or run this as an administrator:

Start-Service SharpDayDeploymentNode

2. Make the config file

The Node does not make its config file for you. Until the file exists, the Node waits and does not accept connections. It looks for the file every 30 seconds, so it starts as soon as you save it.

Make a file called config.xml in C:\Program Files\SharpDay\Deployment Node:

<?xml version="1.0" encoding="utf-8"?>
<SDDNConfig>
  <UserWhiteList>EXAMPLE\svc-deploy</UserWhiteList>
  <Port>4333</Port>
  <EnforceKerberos>true</EnforceKerberos>
  <LoggingLevel>Information</LoggingLevel>
  <LogPath>C:\ProgramData\SharpDay\Deployment Node\Log</LogPath>
  <LogRetention>30</LogRetention>
</SDDNConfig>
Setting What it does Default
UserWhiteList The accounts allowed to connect, with commas between them. See Who can connect. If this is empty, nobody can connect. Empty
Port The port the Node listens on, from 1 to 65535. 4333
EnforceKerberos Set to true to only allow Kerberos and refuse NTLM. false
LoggingLevel How much goes in the log: Verbose, Debug, Information, Warning, Error or Fatal. Information
LogPath The folder for log files. C:\ProgramData\SharpDay\Deployment Node\Log
LogRetention How many days of logs to keep. A whole number above 0. 30

If a value is wrong, the Node writes an error to its log and uses the default.

To keep the config file somewhere else, set the ConfigPath string value in the registry at HKLM\Software\SharpDay\DeploymentNode. Give the full path to the file, including its name, for example D:\SDDN\config.xml.

Note

After you change config.xml, restart the SharpDay Deployment Node service. Only the first time you make the file does the Node read it without a restart.

Who can connect

Write each account in UserWhiteList as DOMAIN\user:

  • Use the short domain name that Windows shows before the \, such as EXAMPLE, not the full name such as example.com.
  • user@example.com does not work. The Node ignores it and writes an error to its log.
  • A user name on its own, such as svc-deploy, is allowed from any domain the server trusts. It never matches a local account on the Node's own server, or a built-in account.

Use the same account you enter for this Node in the Console.

Important

Upgrading from a version before 1.0.0.0? Older versions only checked the user name and ignored the domain. Version 1.0.0.0 checks both, so check your UserWhiteList entries after you upgrade.

3. Add your scripts

Put the scripts you want to run in C:\Program Files\SharpDay\Deployment Node\Scripts. The installer makes this folder. Only administrators can add or change files in it. You cannot move this folder.

  • The Node only runs .ps1, .bat and .exe files.
  • Put scripts straight in the Scripts folder. The Node does not look in folders inside it.
  • Scripts run as the account the service runs as. That is Local System, unless you change it.
  • There is no time limit, so a script must never wait for someone to type something.

What a script gets

The Run SDDN Command step has 3 settings: SDDN Server, Script Name and Arguments. The Node also gets the name of the PC being set up. It refuses a request without one.

File type How it runs What it gets
.ps1 Windows PowerShell, with -NonInteractive -NoProfile -ExecutionPolicy Bypass The PC name as the first argument, and Arguments as the second
.bat cmd.exe The PC name as %1, and Arguments as %2
.exe On its own Only Arguments, as its command line

For .ps1 and .bat files, Arguments reaches the script as one value, even if it has spaces in it. If it is empty, the script does not get it.

An exit code of 0 sends the step down its Success path. Any other exit code sends it down Failure. What the script writes out shows in the workflow log.

4. Check the firewall

The installer adds Windows Firewall rules that let the Node receive connections on Domain and Private networks. If a rule goes missing, the service puts it back each time it starts.

To leave the rules out, install with ADD_FIREWALL_RULE=0. The service then leaves the firewall alone.

If there are other firewalls or VLANs between the SharpDay Deploy server and the Node, allow TCP 4333 (or your port) through them.

Your scripts may need other ports of their own.

5. Add the Node in the Console

  1. In the Console, go to Automations > SDDN Servers and select New server.
  2. Fill in Display name, Service Principal Name, Port, Domain, Username and Password.
  3. Select Save, then Test.

The Service Principal Name is also the address the server connects to. The server takes the part after the /, so in Deploy/server01.example.com it connects to server01.example.com. That name must work in DNS from the SharpDay Deploy server, even if you do not use Kerberos.

Test signs in to the Node and checks the account is in UserWhiteList. If it works, it says the Node accepts this account. If the Node refuses, it says why, for example that the account is not allowed, or that NTLM was used while Kerberos is enforced. The same reasons show in the workflow log when a step fails.

Set up Kerberos

Kerberos is safer than NTLM, but it must be set up correctly. The Node always tries Kerberos first, and falls back to NTLM unless EnforceKerberos is true.

Important

Use a group managed service account (gMSA), not a normal user account. Kerberos needs a service principal name (SPN) on the account, and an SPN on a normal user account makes it easier to attack (this attack is called Kerberoasting). A gMSA has a long password that Windows changes for you.

Tip

Start the service as Local System at least once before you change it to the gMSA. On its first start it writes its registry settings and firewall rules, which a gMSA is not allowed to do.

1. Make an Active Directory group

Make a security group in Active Directory. Add every server that will run the Node to it.

2. Make the gMSA

Change the names, then run this on a domain controller:

New-ADServiceAccount -Name "gmsa_name" -DNSHostName "gmsa_name.example.com" -PrincipalsAllowedToRetrieveManagedPassword "GroupName" -KerberosEncryptionType AES128, AES256
  • gmsa_name is the name of the account.
  • gmsa_name.example.com is the account name followed by your domain name.
  • GroupName is the group you made in step 1.
  • -KerberosEncryptionType is optional. It stops Kerberos falling back to the older RC4 encryption.

3. Add an SPN to the gMSA

Run this on a domain controller once for each server in the group:

setspn -S Deploy/server01.example.com "gmsa_name"
  • Deploy can be any word, but the whole SPN must be unique.
  • server01.example.com is the full name of the server that runs the Node.
  • gmsa_name is the account you made in step 2.
Tip

Enter this same SPN, for example Deploy/server01.example.com, in the Service Principal Name box for this Node on Automations > SDDN Servers.

4. Add the Active Directory PowerShell tools

Run this on each server that runs the Node:

Install-WindowsFeature -Name RSAT-AD-PowerShell

5. Install the gMSA on the server

Run this on each server that runs the Node:

Install-ADServiceAccount -Identity "gmsa_name"
Tip

If you see "An unspecified error has occurred", run gpupdate /force, restart the server and try again.

6. Check the gMSA works

Run this on each server that runs the Node. It should show True.

Test-ADServiceAccount -Identity "gmsa_name"

7. Run the service as the gMSA

  1. Give the gMSA Modify rights on the log folder, C:\ProgramData\SharpDay\Deployment Node\Log.
  2. Open Services.
  3. Double-click SharpDay Deployment Node.
  4. On the Log On tab, choose This account, then Browse, and find your gMSA.
  5. Leave both password boxes empty and select OK.
  6. Restart the service.

Your scripts now run as the gMSA too, so give it the rights they need.

Logs

The Node writes a log file each day to:

C:\ProgramData\SharpDay\Deployment Node\Log\sddn-<date>.log

It also writes warnings and errors to the Windows Application event log, with the source SharpDay Deployment Node.

For more detail in the log, set LoggingLevel to Debug and restart the service.