LDAP Search Update Queries

NetTools supports the ability to not just query the directory, but also perform update as well. Because writing to a directory comes with some risks, there are number of safe guards to make sure that you update the directory by intent and not by mistake.

To use the Update option you have to input the required details in the Attributes field, see the syntax below, you then need to select the Enable Updates option. This will enable the preview mode by default as an extra safety net.  Preview mode allow you to run the query and show the values that would be written to the attributes when the preview mode is turned off.  When Preview mode is deselected the Go button turns red to show that the update mode is enabled and attributes could be changed when the query is run.  Please note, there is no undo option for updates.  When you run an update query the values returned against each of the attributes are the new value for the attributes after the update has been completed.  If an error occurs during the update the LDAP error code is returned, in most case these are self explanatory and are usually due to a schema restriction.  See the Single Update option below for more information on how to determine which update caused the error.

Update Queries will update the Attributes based on the values specified in the attributes field or data specified in the Input Mode columns. To update an attribute an Update Operator must be specified after the attribute name, follow with the value you wish to set.  This is the Syntax for the update operation:

Syntax: <Attribute><Op><Value>

Attribute:  The name of the attribute that you wish to update
Op: The Update Operation that is to be performed

=+        Add Value to attribute
=-         Remove the Value from the Attribute, if no Value is specified the attribute is cleared
==        Set\Replace the current value of the attribute with Value
=|         Perform a bitwise operation of the current value of the attribute, this Op has a specific format for the Value, see mask details below
=#        Delete the object from the directory
=>        Move the object the new location specified by the Value, the Value should be encapsulated in quote marks 

Value = <Mask>:<Data>

Mask - the bitwise mask  Note: Input Mode substitution can’t be used on this field, only the data field 
Data - is the bits to be set based on the bit mask
Value - the data to be written to the attribute

The Add operator ‘=+’ can fail due of the schema definition of an attribute that is being updated.  If you use the Add operator to update an attribute that has a schema definition of single value, if there is no value assigned to the attribute the update will succeed. However, if there is a value already assigned, the update will fail.  In the case of a single value attribute its better to use the Set ‘==’ operator to assign the new value, as this will set or replace the existing value.

The value provided to update attributes can use the same substitution options that are available in the filter field i.e sid, oid, ip, ipn, idate, zdate, hex, guid, unicode, and userinput.  There is additional substitutions options for the attributes field, these are attrib and code characters.  The attrib substitution option can be used to retrieve the value of attributes on the object being updated, this is useful for updating multiple line single value attributes like the Info field.  To retrieve the value of a specific attribute, this doesn’t have to be the same attribute as the one that is being updated, you only need to specify the attribute name in the subst command i.e. {attrib:info}.  The support for the retrieval of a value is limited to attributes that only have a single value set.  If multiple values are assigned to the attribute the retrieval will fail and report an error that multiple values exist.  The substitution also supports the use of the standard C\C++ Escape characters to include control character or binary values, these are listed below.       

C\C++ Escape Characters:

\a         07        Alarm (Beep, Bell)
\b         08        Backspace
\f          0C        Formfeed
\n         0A        Newline (Line Feed); see notes below
\r          0D       Carriage Return
\t          09        Horizontal Tab
\v         0B        Vertical Tab
\\         5C       Backslash
\'          27        Single quotation mark
\"         22        Double quotation mark
\?         3F         Question mark
\hh       any       The character whose numerical value is given by hh interpreted as a hexadecimal number

The batch mode feature provides the ability to run a number of saved queries in a specified order.  It can be used to complete management tasks, one example is the automation of disabling inactive accounts.  This is achieved by creating a query that returns all accounts that are inactive based on your audit requirement, then the next query in the batch list is an update query that is configured as input query taking the results from the first query as an input, these accounts are then disabled by the second query. 

The subst option userinput can be used to prompt the user for input.  The userinput will prompt the user for an input, the input has a label which is shown on the dialog box, the label is specified in the subst command.  The user inputs are cached against the label, if a label is used a second time the cached response is used and the user is not prompted. The userinput subst can be nested in other subst options e.g. (pwdpastset>={idate:{userinput:Date}}) the user will be prompted to enter the date, then the idate subst will convert this into a 64bit date code. 

Examples:

ExtensionAttribute1==Office1                            - Sets the ExtensionAttribute1 to Office1
ProxyAddresses=+smtp:www.world.com             - Adds the value to the ProxyAddresses, the existing values are preserved
ProxyAddresses=-smtp:www.world.com              - Removes the specific value from the attribute
ProxyAddresses=-                                                 - Clear the attribute, i.e. set to not set
UserAccountControl=|2:2                                     - Sets the 2 bit of the attribute to 1
UserAccountControl=|2:0                                     - Clears the 2 bit of the attribute to 0
UserAccountControl=|6:4                                     - Clears the 2 bit and sets the 4 bit of the attribute
dn=>”cn=users,dc=domain,dc=com”                  - Move the selected object to the specified location
dn=#                                                                     - Delete the object from Active Directory
UserAccountControl=|2:##input2                         - sets bit 2 to the value of ##input2

Info=={attrib:info}\n user updated as part of change 31012
Info=={attrib:info}{attrib:mail} user updated as part of change 31012
Objectversion=={attrib:objectversion}1
Binary=+\23\34\01\5a\4f\00

The Update mode can be combined with the multi-column Input Mode to update the attributes of objects with different values.  For example if you wanted to update the department and telephone numbers for a number of users.  If you paste three columns of data into the table view containing a list of samaccountname, department name, and new telephone number and then by setting the Filter field to (samaccountname=##input) and the attribute field to Department==##input2, telephone==##input3 you can update all the users details in one operation.  Another example if you have a list of users that need to be disabled and another list of users that need to be enabled.  If you combine the list of samaccountname and in the second column specify 0 for an account you want to enable and 2 for an account you want to disable.  Pasting these columns into the table view and set the Filter field the same as with the previous example but setting the Attribute field to UserAccountControl=|2:##input2, this will update all the accounts in one operation.

Enable Updates - When selected the the update query is available 

Single Update - is the default when the Update mode is selected, this causes all the required updates to be performed as a single update operation when the query is run.  The disadvantage to using single update is if you update multiple attributes at once and one of the updates fails i.e. due to a schema restriction, the resulting error message which is reported is against the first attribute that is displayed and not the attribute that caused the update to fail.  By deselected Single Update option, each update is performed separately and if that update fails the error message is display against the attribute that caused the update to fail.

Object Deletion - the delete operator is only available when this option is selected

Delete Tree - when selected the delete operation is preformed as a delete tree operation and all sub items will also be deleted.  If this option is not selected and there are child items the delete will fail

Preview - this option is enabled by default when the Enable Updates option is selected, if the query is run with the preview options selected the returned values are the values that would be written to the attributes when the preview option is not selected.  After an update query is run the preview option is automatically selected again

Display Results - This option is used to suppress the displaying of the results, this is useful if you are updating an attribute that contains a large number of values, i.e. group memberships, and will significantly increase the performance of the update query.

Note: with the delete and move operators, the attribute used to specify the delete operator, must have a value for the operation to be executed.  The best attribute to use in this case is one that must have an attribute i.e. dn or objectclass

Permissions Caching

 

NetTools uses local caching to improve the performance when viewing the permissions in ACL Browser and GPO Explorer.  The cache is used to cache Control Assess Rights GUIDs and resolved SIDs, this makes viewing the permissions of subsequent objects significantly faster.  ACL Browsers and GPO Explorer use the same cache to improve performance across these options.  If ACL Browser and GPO Explorer interrogate the same forest then both options will benefit from the caching.  However, when they are pointing at different forests, the cache is cleared and caching is started again when a different context is detected, resulting in an initial performance hit as the cache is reseeded.

LDAP Search – Paged Query Support

Active Directory limits the number of results that can be returned in a single query, this is defined by the MaxPageSize settings in the LDAP Query Policy, the default value is 1000.  If the results of a query exceeds this limit, the server will return a Size limit was exceeded (0x4) error.  To overcome this limit you need to use the Paged Server Side Control, which will return the results over a number of responses, with the total number of results per response not exceeding the MaxPageSize value.  NetTools has the Paged Control is enabled by default and will automatically reconstruct the results into a single output.

The MaxPageSize value is defined in Default Query Policy stored in the configuration partition.

CN=Default Query Policy,CN=Query-Policies,CN=Directory Service,CN=Windows NT,CN=Services,CN=Configuration,DC=x

Attribute - lDAPAdminLimits

You can also define a separate Query Policy at the domain controller and AD site levels, these can be viewed using the Site Browser option.

.

LDAP Search – Dynamic and Sort Attributes Options

These two options control how NetTools will display attributes in the LDAP Search option. 

Dynamic Attributes
By default the Dynamic Attributes option is selected, with this option selected, when the LDAP Search query is run, NetTools will query the Schema for a set of known attribute type and assign the corresponding Decode Type to the attribute.  When the attribute is displayed, the decode type will be used to display the contents of the attribute.

Sort Attribute
This option is also enabled by default and causes the schema to queried to retrieve the details of the selected output attributes, the results are then assigned to the table view sort function, so the attributes are sorted correctly associated to the attribute type, i.e. number, text, date, IP address, etc.  If this option is turn off, all data will be sorted based on the default alpha sort function.  

Both of these options cause additional data to be requested from the server, this can impact the time taken to display the results, especially if the target server is on the other end of a slow link.  Turning these options off is a balancing between function and speed.

Decode Types

At the heart of NetTools is a LDAP client that includes a decode engine that will decode attributes so that the data can be displayed in a readable format.  The decode engine includes over 40 predefined decode types.  These decodes can be assigned to a specific attribute using four different methods.

These are Static, Dynamic, User Defined, and Manual Override:

The Static assignment are statically defined within NetTools, i.e. WhenChanged is associated to the GTFTIME decode type.  These can be overridden by User Defined and Manual Override assignments. See Static DecodeTypes
While Dynamic will assign the decode type associated to an object based on the schema definition of the attributes. i.e. attributes that binary and have a fixed length of 32 and guid in the name will automatically be assigned the GUID decode type.
User Defined assigned decode types can be assigned a few different ways in NetTools, from the LDAP Search's Manage Dynamic Attribute Decodes dialog, via the define decode type dialog from the context menu in the Schema Class Browser option, or via the configuration file.  

NetTools.ini Example:     

[AttributeDecodes]
msExchBlockedSendersHash=BIN

The Manual Override option is only available in the LDAP Search option, when specifying the attributes to be displayed in the output, you can also include a Decode type as an extra parameter of the attribute, i.e. msExchBlockedSendersHash;bin.  This overrides all other definition and displays the data in a Binary format.

This is the list of decode type that are available in NetTools:

    DEFAULT - ASCII
    64DATE - Win32 64bit Date Format
    64TIME - Win32 64bit Date & Time Format, local time
    64TIME_UTC - Win32 64bit Date & Time Format, UTC
    ATTRIBENUM - predefined enumerate
    ATTRIBENUM_NONUM - predefined enumerate only symbolics are displayed
    BASE64 - encode the returned value as Base64    
    BEROID - Basic Encoding Rules (BER) Organization Identifier
    BIN - Binary output
    CERT - Certificates
    COUNT - Returns the number of entries in the attribute
    CRL - Certificate Revocation List
    DNSPROPERTY - DNS Properties entries
    DNSRECORD - DNS entries
    DNSRECORD.DATA - return only the data field
    DNSRECORD.RANK - return only the rank field
    DNSRECORD.SERIAL - return only the serial field
    DNSRECORD.TIMEOUT - return only the timeout field
    DNSRECORD.TIMESTAMP - return only the timestamp field
    DNSRECORD.TTL - return only the ttl field
    DNSRECORD.TYPE - return only the type type field
    DNSRECORD.VERSION - return only the version field
    DSA_SIG - DSA Signature
    FILETIME - Win32 File Date & Time Format
    GTFTIME - Generalized Time Format, local time
    GTFTIME_UTC - Generalized Time Format, UTC
    GMSAPWD - return the full details of the gMSA password
    GMSAPWD.PWD - return only the current password
    GMSAPWD.PPWD - return only the previous password
    GMSAPWD.QRY - return the query interval
    GMSAPWD.UCG - return the change interval
    GMSAPWDID - return the full gMSA PasswordID details
    GMSAPWDID.RK - return the gMSA PasswordID Root Key
    GMSAPWDID.SVR - return the gMSA PasswordID server
    GUID - Windows COM GUID format
    GUID_LDAP - GUID in LDAP filter format
    GUID_RAW - Hex GUID format
    HEX - Display a number if Hex format
    IP - DWORD IP address in windows order
    IPN - DWORD IP address in network order
    META - Decoder for msDS-ReplAttributeMetaData
    METAV - Decoder for msDS-ReplValueMetaData
    MSTRUST - Decoder for msds-TrustForestTrustInfo
    NANOTIME - Display interval based on nano seconds
    NTDS_CONN_OPT - Returns the options for the Options of NTDSConnection
    NTDS_DSA_OPT - Returns the options for the Options of NTDSDSA
    NTDSSSITE_OPT - Returns the options for the Options of NTDS Sites Settings
    PARENTCN - Returns the parent container of the CanonicalName
    PARENTDN - Returns the parent container of the distinguishedName
    PERIOD - Certificate renewal period
    PSMTP - Display primary smtp entry
    PWDSEC - Password secounds
    PX400 - Display primary x400 entry
    PX500 - Display primary x500 entry
    REPL_UTDV - NC Up ToDateness Vectors
    REPS_INFO - Replication neighbours RepsTo and RepsFrom
    RIDPOOL - RID Pool Allocations
    SD - Security Descriptor in SDDL format
    SD_DACL_COUNT - Returns the number of ACE in the DACL
    SD_DACL_EXPCOUNT - Returns the number explicitly assigned ACE in the DACL
    SD_NAME - Returns the resolved names of all the entries in the SD
    SD_NAME_DACL - Returns the resolved names of the DACL entries in the SD
    SD_NAME_GROUP - Return the primary group assigned in the SD
    SD_NAME_OWNER - Returns the resolved name of the owner in the SD
    SD_NAME_SACL - Returns the resolved names of the SACL entries in the SD
    SD_SACL_COUNT - Returns the number of ACE in the SACL
    SD_SACL_EXPCOUNT - Returns the number explicitly assigned ACE in the DACL
    SD_SID - Returns the SID of all entries in the SD
    SD_SID_DACL - Returns the SID of the DACL entries in the SD
    SD_SID_GROUP – Returns the primary group assigned in the SD
    SD_SID_OWNER - Returns the SID of the Owner in the SD
    SD_SID_SACL - Returns the SID of the SACL entries in the SD
    SID - Display Security Identifier in text form
    SID_ABS - Display the absolute name of the SID
    SID_REL - Display the relative name of the SID
    SITE_LINK_OPT - Returns the options for the Options of SiteLink
    SIZE - The size of the data returned
    SMTP - Display only smtp entries
    TRANSPORT_OPT - Returns the options for the Options of transport container
    UNICODE - Return a string in Unicode format, with BOM decode support
    WMITime - Returns the wmi time 
    WMITime_UTC - Returns the utc wmi time
    X400 - Display only x400 entries
    X500 - Display only x500 entries

A debug option exists that will display which decode type was used to decode the displayed attributes, the debug information is only displayed in the LDAP Search text output pane.  This debug feature can only be enabled by added the following entry to the NetTools.ini configuration file.

[SavedOptions]
DebugDecoder=true