Windows Server Windows Server: Inputs & Outputs

Summary

Each plugin uses a set of dictionaries to store data.

These are used by plugin actions as both inputs and outputs.

This page will cover:

  • The dictionaries used in this plugin
  • The information each dictionary contains

Info

See Commands & Files for each action's inputs & outputs.

Dictionary Types

DNSRecord

  • Contains Windows DNS record details

Example - A Record

1
2
3
4
5
6
7
8
hostname: iis-001
type: A
time_to_live:
  days: 0
  hours: 1
  minutes: 0
  seconds: 0
data: IPv4Address = "10.9.10.10"

Example - CName Record

1
2
3
4
5
6
7
8
hostname: web-server
type: CNAME
time_to_live:
  days: 0
  hours: 1
  minutes: 0
  seconds: 0
data: HostNameAlias = "iis-001.internal.net."

Example - PTR Record

1
2
3
4
5
6
7
8
hostname: 10.9.10.10
type: PTR
time_to_live:
  days: 0
  hours: 1
  minutes: 0
  seconds: 0
data: PtrDomainName = "iis-001.internal.net"

DNSRecord Keys

hostname: The record hostname.

type: The record type (A, CNAME, or PTR).

time_to_live: Dictionary containing the TTL in days, hours, minutes, & seconds.

data: Record-specific data (see examples above for more).

DNSZone

  • Contains Windows DNS zone details

Example

1
2
3
4
5
6
name: internal.net
type: Primary
is_auto_created: false
is_ds_integrated: true
is_reverse_lookup_zone: false
is_signed: false

DNSZone Keys

name: The name of the zone.

type: The zone type.

is_auto_created: Indicates whether the zone was created automatically.

is_ds_integrated: Indicates whether the zone is integrated with Active Directory.

is_reverse_lookup_zone: Indicates whether the zone is a reverse lookup zone.

is_signed: Indicates whether the zone is signed.

Group

  • Contains Windows group details

Example

1
2
3
name: Administrators
description: Administrators have complete and unrestricted access to the computer/domain
sid: S-1-5-21-2746729022-1139076888-119054876-500

Group Keys

name: The name of the group.

description: The group description.

sid: The group object SID.

RDPSession

  • Contains RDP session details

  • The example below shows the dictionary structure in YAML

Example

1
2
3
4
5
rdp_session:
  username: domain\username
  session_name: rdp-tcp#50
  state: Active
  id: 2
All RDPSession Keys

id: The RDP session ID on the Windows Server.

username: The username the RDP session was authenticated with.

session_name: The name of the RDP session.

state: The state of the RDP session (Disconnected, Connected, Active, Listening).

Service

  • Contains Windows service details

  • The example below shows the dictionary structure in YAML

Example

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
name: Dhcp
display_name: DHCP Client
state: Running
status: OK
start_name: NT Authority\\LocalService
description: >
  Registers and updates IP addresses and DNS records for this computer.
  If this service is stopped, this computer will not receive dynamic IP addresses
  and DNS updates. If this service is disabled, any services that explicitly depend
  on it will fail to start.
All Service Keys

name: The name of the service.

display_name: The display name for the service.

state: The state of the service.

status: The service status.

start_name: The account the service runs under.

description: The service description.

User

  • Contains Windows user account details

  • The example below shows the dictionary structure in YAML

Example

1
2
3
4
5
6
7
8
9
name: Administrator
full_name: ''
description: Built-in account for administering the computer/domain
disabled: false
locked: false
password_changeable: true
password_expires: true
password_required: true
sid: S-1-5-21-2746729022-1139076888-119054876-500

User Keys

name: The name of the user.

full_name: The user's full name.

description: The user description.

disabled: Indicates whether the user is disabled.

locked: Indicates whether the user is locked.

password_changeable: Indicates whether the user can change their own password.

password_expires: Indicates whether the user's password will expire.

password_required: Indicates whether a password is required to log on as this user.

sid: The user account object SID.

WindowsServer

  • Contains remote Powershell connection details for a Windows Server

  • It is used as an input to many of the actions in this plugin

  • The example below shows the dictionary structure in YAML

  • See the required and optional keys underneath the example

Authentication Methods

PPA v2.7.0 introduces support for Kerberos authentication, on top of the existing NTLM support.

If a username & password are supplied, NTLM authentication will be attempted.

To use Kerberos authentication, just omit the username & password.

Kerberos support requires plugin version 2.0.0 and newer.

Supplying Credentials

You should always use a PPA Vault integration to provide credentials to a plugin action.

Authenticating Using Kerberos

When authenticating to a Windows server using Kerberos, the server must have the following Service Principal Names set:

    WSMAN/{hostname}
    WSMAN/{FQDN}

For more information regarding Service Principal Names, click here

Kerberos Authentication

Requires PPA v2.7.0 or newer, & plugin version 2.0.0 or newer.

1
2
windows_server:
  address: windows-server.internal.net

NTLM Authentication

1
2
3
4
windows_server:
  address: windows-server.internal.net
  username: example_username
  password: example_password

Required Keys

address: The target IP or DNS address.

Optional Keys

username: Username for authentication (if using NTLM authentication).

password: Password for authentication (if using NTLM authentication).

validate_cert: Set to false to skip certificate validation (defaults to true).

use_ssl: Set to false to connect over HTTP (defaults to true using HTTPS).

read_timeout: The timeout in seconds for receiving a response from the server (defaults to 30).

operation_timeout: The timeout in seconds for each remote Powershell operation (defaults to 20.