Public/Get-ALHDSDomainController.ps1

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
461
462
463
464
465
466
467
468
469
470
471
472
473
474
475
476
477
478
479
480
481
482
483
484
485
486
487
488
489
490
491
492
493
494
495
496
497
498
499
500
501
502
503
504
505
506
507
508
509
510
511
512
513
514
515
516
517
518
519
520
521
522
523
524
525
526
527
528
529
530
531
532
533
534
535
536
537
<#PSScriptInfo
 
.VERSION 1.0.1
 
.GUID e6e6b2bd-ffa8-4c53-a1fe-f383723729e1
 
.AUTHOR Dieter Koch
 
.COMPANYNAME
 
.COPYRIGHT (c) Dieter Koch
 
.TAGS
 
.LICENSEURI https://github.com/admins-little-helper/ALH/blob/main/LICENSE
 
.PROJECTURI https://github.com/admins-little-helper/ALH
 
.ICONURI
 
.EXTERNALMODULEDEPENDENCIES
 
.REQUIREDSCRIPTS
 
.EXTERNALSCRIPTDEPENDENCIES
 
.RELEASENOTES
    1.0.0
    Initial release
 
    1.0.1
    Changed type for parameter DomainName
 
#>



<#
 
.DESCRIPTION
 Function to query Active Directory Domain Controller based on DsGetDcName function
 https://docs.microsoft.com/en-us/windows/win32/api/dsgetdc/nf-dsgetdc-dsgetdcnamea
 
 Based on script from Jordan Borean (Jordan Borean (@jborean93) <jborean93@gmail.com>)
 https://gist.github.com/jborean93/6c3d8b64aa994c2676c6cc249bbf8833
 
 #>




function Get-ALHDSDomainController {
    <#
    .SYNOPSIS
    Locate a domain controller.
 
    .DESCRIPTION
    Locates a domain controller and returns the name and some additional information for about it.
 
    .PARAMETER DomainName
    The name of the Active Directory domain to search a DC for.
 
    .PARAMETER Server
    The name of the server to run the search from.
 
    .PARAMETER DomainGuid
    The GUID of the domain to find. This is used if the DC cannot be found by DomainName.
 
    .PARAMETER SiteName
    The name of the site where the DC should exist.
 
    .PARAMETER DirectoryServiceRequired
    Require the DC to support directory services.
 
    .PARAMETER DirectoryServicePreferred
    Prioritise DCs that support directory services over ones that do not.
 
    .PARAMETER GlobalCatalogRequired
    Require the DC to be a global catalog server for the forest of domains with this domain as the root.
 
    .PARAMETER PrimaryDCRequired
    Finds the DC that is the primary domain controller for the domain.
 
    .PARAMETER NoCache
    Forces cached information to be ignored.
 
    .PARAMETER UseCache
    Always use the cached information even when the function would normally refresh the data.
 
    .PARAMETER IpRequired
    The DC must have an IP address.
 
    .PARAMETER KdcRequired
    The DC must be a kerberos key distribution center.
 
    .PARAMETER TimeservRequired
    Requires the DC be currently running the Windows Time Service.
 
    .PARAMETER WritableRequired
    The DC must be writable and not a read only copy.
 
    .PARAMETER GoodTimeservPreferred
    Finds a DC that is a reliable time server.
 
    .PARAMETER AvoidSelf
    When calling from a domain controller, specified that the returned DC should not be the current host.
 
    .PARAMETER OnlyLdapNeeded
    Find a host that is an LDAP server and not necessarily a DC.
 
    .PARAMETER IsFlatName
    The -DomainName value is a flag name, e.g. DOMAIN. This cannot be combined with IsDnsName.
 
    .PARAMETER IsDnsName
    The -DomainName value is a DNS name, e.g. domain.com. This cannot be combined with IsFlagName.
 
    .PARAMETER TryNextClosestSite
    Attempt to find a DC in the same site but if nothing is found try the next closest site.
 
    .PARAMETER WebServiceRequired
    Requires the DC to be running the Active Directory web service.
 
    .PARAMETER Server2008OrLater
    DC must be running Windows Server 2008 or later.
 
    .PARAMETER Server2012OrLater
    DC must be running Windows Server 2012 or later.
 
    .PARAMETER Server2012R2OrLater
    DC must be running Windows Server 2012 R2 or later.
 
    .PARAMETER Server2016OrLater
    DC must be running Windows Server 2016 or later.
 
    .PARAMETER ReturnDnsName
    Returns the DNS names for Name and DomainName. This cannot be combined with ReturnFlatName.
 
    .PARAMETER ReturnFlatName
    Returns the flag name for Name and DOmain Name. This cannot be combined with ReturnDnsName.
 
    .EXAMPLE
    Get-ALHDSDomainController
 
    .INPUTS
    None
 
    .OUTPUTS
    Nothing
 
    .NOTES
    Author: Dieter Koch
    Email: diko@admins-little-helper.de
 
    .LINK
    https://github.com/admins-little-helper/ALH/blob/main/Help/Get-ALHDSDomainController.txt
    #>


    [CmdletBinding()]
    param (
        [String]
        $DomainName = (Get-CimInstance -ClassName "Win32_ComputerSystem").Domain,

        [String]
        $Server,

        [Nullable[Guid]]
        [AllowNull()]
        $DomainGuid = $null,

        [String]
        $SiteName,

        [Switch]
        $DirectoryServiceRequired,

        [Switch]
        $DirectoryServicePreferred,

        [Switch]
        $GlobalCatalogRequired,

        [Switch]
        $PrimaryDCRequired,

        [Switch]
        $NoCache,

        [Switch]
        $UseCache,

        [Switch]
        $IpRequired,

        [Switch]
        $KdcRequired,

        [Switch]
        $TimeservRequired,

        [Switch]
        $WritableRequired,

        [Switch]
        $GoodTimeservPreferred,

        [Switch]
        $AvoidSelf,

        [Switch]
        $OnlyLdapNeeded,

        [Switch]
        $IsFlatName,

        [Switch]
        $IsDnsName,

        [Switch]
        $TryNextClosestSite,

        [Switch]
        $WebServiceRequired,

        [Switch]
        $Server2008OrLater,

        [Switch]
        $Server2012OrLater,

        [Switch]
        $Server2012R2OrLater,

        [Switch]
        $Server2016OrLater,

        [Switch]
        $ReturnDnsName,

        [Switch]
        $ReturnFlatName
    )

    Add-Type -TypeDefinition @'
using System;
using System.ComponentModel;
using System.Runtime.InteropServices;
 
namespace NetApi
{
    public class NativeHelpers
    {
        [StructLayout(LayoutKind.Sequential, CharSet = CharSet.Unicode)]
        public struct DOMAIN_CONTROLLER_INFOW
        {
            public string DomainControllerName;
            public string DomainControllerAddress;
            public DCAddressType DomainControllerAddressType;
            public Guid DomainGuid;
            public string DomainName;
            public string DnsForestName;
            public DCFlags Flags;
            public string DcSiteName;
            public string ClientSiteName;
        }
    }
 
    public class NativeMethods
    {
        [DllImport("NetApi32.dll", CharSet = CharSet.Unicode)]
        private static extern Int32 DsGetDcNameW(
            string ComputerName,
            string DomainName,
            IntPtr DomainGuid,
            string SiteName,
            GetDcFlags Flags,
            out IntPtr DomainControllerInfo);
 
        [DllImport("NetApi32.dll")]
        private static extern Int32 NetApiBufferFree(
            IntPtr Buffer);
 
        public static DCInfo DsGetDcName(string domainName, string computerName = null, string siteName = null,
            GetDcFlags flags = GetDcFlags.None, Guid? domainGuid = null)
        {
            IntPtr rawInfo;
            IntPtr domainGuidPtr = IntPtr.Zero;
            try
            {
                if (domainGuid != null)
                {
                    byte[] guidBytes = ((Guid)domainGuid).ToByteArray();
                    domainGuidPtr = Marshal.AllocHGlobal(guidBytes.Length);
                    Marshal.Copy(guidBytes, 0, domainGuidPtr, guidBytes.Length);
                }
 
                Int32 res = DsGetDcNameW(computerName, domainName, domainGuidPtr, siteName, flags, out rawInfo);
                if (res != 0)
                    throw new Win32Exception(res);
            }
            finally
            {
                if (domainGuidPtr != IntPtr.Zero)
                    Marshal.FreeHGlobal(domainGuidPtr);
            }
 
            try
            {
                var info = (NativeHelpers.DOMAIN_CONTROLLER_INFOW)Marshal.PtrToStructure(rawInfo,
                    typeof(NativeHelpers.DOMAIN_CONTROLLER_INFOW));
 
                return new DCInfo()
                {
                    Name = info.DomainControllerName,
                    Address = info.DomainControllerAddress,
                    AddressType = info.DomainControllerAddressType,
                    DomainGuid = info.DomainGuid,
                    DomainName = info.DomainName,
                    DnsForestName = info.DnsForestName,
                    Flags = info.Flags,
                    DcSiteName = info.DcSiteName,
                    ClientSiteName = info.ClientSiteName,
                };
            }
            finally
            {
                NetApiBufferFree(rawInfo);
            }
        }
    }
 
    public class DCInfo
    {
        public string Name { get; internal set; }
        public string Address { get; internal set; }
        public DCAddressType AddressType { get; internal set; }
        public Guid DomainGuid { get; internal set; }
        public string DomainName { get; internal set; }
        public string DnsForestName { get; internal set; }
        public DCFlags Flags { get; internal set; }
        public string DcSiteName { get; internal set; }
        public string ClientSiteName { get; internal set; }
    }
 
    public enum DCAddressType : uint
    {
        INetAddress = 1,
        NetbiosAddress = 2,
    }
 
    [Flags]
    public enum DCFlags : uint
    {
        Pdc = 0x00000001,
        Gc = 0x00000004,
        Ldap = 0x00000008,
        Ds = 0x00000010,
        Kdc = 0x00000020,
        Timeserv = 0x00000040,
        Closest = 0x00000080,
        Writable = 0x00000100,
        GoodTimeserv = 0x00000200,
        Ndnc = 0x00000400,
        SelectSecretDomain6 = 0x00000800,
        FullSecretDomain6 = 0x00001000,
        Ws = 0x00002000,
        Ds8 = 0x00004000,
        Ds9 = 0x00008000,
        Ds10 = 0x00010000,
        Ping = 0x000FFFFF,
        DnsController = 0x20000000,
        DnsDOmain = 0x40000000,
        DnsForest = 0x80000000,
    }
 
    [Flags]
    public enum GetDcFlags : uint
    {
        None = 0x00000000,
        ForceRediscovery = 0x00000001,
        DirectoryServiceRequired = 0x00000010,
        DirectoryServicePreferred = 0x00000020,
        GcServerRequired = 0x00000040,
        PdcRequired = 0x00000080,
        BackgroundOnly = 0x00000100,
        IpRequired = 0x00000200,
        KdcRequired = 0x00000400,
        TimeservRequired = 0x00000800,
        WritableRequired = 0x00001000,
        GoodTimeservPreferred = 0x00002000,
        AvoidSelf = 0x00004000,
        OnlyLdapNeeded = 0x00008000,
        IsFlatName = 0x00010000,
        IsDnsName = 0x00020000,
        TryNextClosestSite = 0x00040000,
        DirectoryService6Required = 0x00080000,
        WebServiceRequired = 0x00100000,
        DirectoryService8Required = 0x00200000,
        DirectoryService9Required = 0x00400000,
        DirectoryService10Required = 0x00800000,
        ReturnDnsName = 0x40000000,
        ReturnFlatName = 0x80000000,
    }
}
'@


    $ServerValue = if ($Server) { $Server } else { [NullString]::Value }
    $siteNameValue = if ($SiteName) { $SiteName } else { [NullString]::Value }
    [NetApi.GetDcFlags]$flags = [NetApi.GetDcFlags]::None

    if ($DirectoryServiceRequired) {
        $flags = [UInt32]$flags -bor [UInt32][NetApi.GetDcFlags]::DirectoryServiceRequired
    }

    if ($DirectoryServicePreferred) {
        $flags = [UInt32]$flags -bor [UInt32][NetApi.GetDcFlags]::DirectoryServicePreferred
    }

    if ($GlobalCatalogRequired) {
        $flags = [UInt32]$flags -bor [UInt32][NetApi.GetDcFlags]::GcServerRequired
    }

    if ($PrimaryDCRequired) {
        $flags = [UInt32]$flags -bor [UInt32][NetApi.GetDcFlags]::PdcRequired
    }

    if ($NoCache) {
        $flags = [UInt32]$flags -bor [UInt32][NetApi.GetDcFlags]::ForceRediscovery
    }

    if ($UseCache) {
        $flags = [UInt32]$flags -bor [UInt32][NetApi.GetDcFlags]::BackgroundOnly
    }

    if ($IpRequired) {
        $flags = [UInt32]$flags -bor [UInt32][NetApi.GetDcFlags]::IpRequired
    }

    if ($KdcRequired) {
        $flags = [UInt32]$flags -bor [UInt32][NetApi.GetDcFlags]::KdcRequired
    }

    if ($TimeservRequired) {
        $flags = [UInt32]$flags -bor [UInt32][NetApi.GetDcFlags]::TimeservRequired
    }

    if ($WritableRequired) {
        $flags = [UInt32]$flags -bor [UInt32][NetApi.GetDcFlags]::WritableRequired
    }

    if ($GoodTimeservPreferred) {
        $flags = [UInt32]$flags -bor [UInt32][NetApi.GetDcFlags]::GoodTimeservPreferred
    }

    if ($AvoidSelf) {
        $flags = [UInt32]$flags -bor [UInt32][NetApi.GetDcFlags]::AvoidSelf
    }

    if ($OnlyLdapNeeded) {
        $flags = [UInt32]$flags -bor [UInt32][NetApi.GetDcFlags]::OnlyLdapNeeded
    }

    if ($IsFlatName) {
        $flags = [UInt32]$flags -bor [UInt32][NetApi.GetDcFlags]::IsFlatName
    }

    if ($IsDnsName) {
        $flags = [UInt32]$flags -bor [UInt32][NetApi.GetDcFlags]::IsDnsName
    }

    if ($TryNextClosestSite) {
        $flags = [UInt32]$flags -bor [UInt32][NetApi.GetDcFlags]::TryNextClosestSite
    }

    if ($WebServiceRequired) {
        $flags = [UInt32]$flags -bor [UInt32][NetApi.GetDcFlags]::WebServiceRequired
    }

    if ($Server2008OrLater) {
        $flags = [UInt32]$flags -bor [UInt32][NetApi.GetDcFlags]::DirectoryService6Required
    }

    if ($Server2012OrLater) {
        $flags = [UInt32]$flags -bor [UInt32][NetApi.GetDcFlags]::DirectoryService8Required
    }

    if ($Server2012R2OrLater) {
        $flags = [UInt32]$flags -bor [UInt32][NetApi.GetDcFlags]::DirectoryService9Required
    }

    if ($Server2016OrLater) {
        $flags = [UInt32]$flags -bor [UInt32][NetApi.GetDcFlags]::DirectoryService10Required
    }

    if ($ReturnDnsName) {
        $flags = [UInt32]$flags -bor [UInt32][NetApi.GetDcFlags]::ReturnDnsName
    }

    if ($ReturnFlatName) {
        $flags = [UInt32]$flags -bor [UInt32][NetApi.GetDcFlags]::ReturnFlatName
    }

    if ($IsDnsName -and $IsFlatName) {
        Write-Error -Message "Cannot specify IsDnsName and IsFlatName together" -Category InvalidArgument
        return
    }

    if ($ReturnDnsName -and $ReturnFlatName) {
        Write-Error -Message "Cannot specify ReturnDnsName and ReturnFlatName together" -Category InvalidArgument
        return
    }

    [NetApi.NativeMethods]::DsGetDcName(
        $DomainName,
        $ServerValue,
        $siteNameValue,
        $flags,
        $DomainGuid
    )
}

#region EndOfScript
<#
################################################################################
################################################################################
#
# ______ _ __ _____ _ _
# | ____| | | / _| / ____| (_) | |
# | |__ _ __ __| | ___ | |_ | (___ ___ _ __ _ _ __ | |_
# | __| | '_ \ / _` | / _ \| _| \___ \ / __| '__| | '_ \| __|
# | |____| | | | (_| | | (_) | | ____) | (__| | | | |_) | |_
# |______|_| |_|\__,_| \___/|_| |_____/ \___|_| |_| .__/ \__|
# | |
# |_|
################################################################################
################################################################################
# created with help of http://patorjk.com/software/taag/
#>

#endregion