Skip to content

Commit d5e2de1

Browse files
authored
Merge pull request #297 from clairecadman/sqlserver_doc_edits
(MODULES-8721) README edit
2 parents bddc857 + e28a162 commit d5e2de1

File tree

1 file changed

+33
-33
lines changed

1 file changed

+33
-33
lines changed

README.md

+33-33
Original file line numberDiff line numberDiff line change
@@ -1063,48 +1063,50 @@ Default: `false`.
10631063

10641064
#### sqlserver::get_sql_logins
10651065

1066-
This task will retrieve information about a login, or a set of logins, from the sql instances running on a given node.
1067-
With no parameters specified it will return summary level information about all logins configured for all sql instances running on a given node or node set.
1068-
Use the `detailed` parameter to return more detailed information including the SID's and the name of the instance a login was retrieved from.
1066+
This task retrieves information about a login, or a set of logins, from the sql instances running on a node.
1067+
1068+
When no parameters are specified, it returns summary level information about all of the logins configured for all sql instances running on a node or node set.
1069+
1070+
Use the `detailed` parameter to return more detailed information, including the SID's and the name of the instance a login was retrieved from.
10691071

10701072
##### parameters
10711073

10721074
* **instance_name**
10731075

10741076
The name of the instance to query for logins. By default, leave blank for all instances running on a node.
10751077
Pass the values `.`, `MSSQLSERVER`, or the node name to query just the default instance.
1076-
Named instances can be referred to by either the short name of the instance, or by `<COMPUTERNAME>\<INSTANCE_NAME>`.
1077-
This is an optional parameter which will accept a single string or array of strings as input.
1078+
Refer to named instances either by the short name of the instance or by `<COMPUTERNAME>\<INSTANCE_NAME>`.
1079+
This is an optional parameter which accepts a single string or array of strings as input.
10781080

10791081
* **login_name**
10801082

10811083
The name of a particular login to search for, or the search pattern for a set of logins.
1082-
If no value is passed to this variable then all logins are returned.
1084+
If no value is passed to this variable, all logins are returned.
10831085
By default any values passed to this parameter are treated like a search string.
10841086
Searches are done using the PowerShell `-match` operator.
10851087
For example, if the string `sql` is passed to this parameter, logins such as `NT SERVICE\SQLWriter`
10861088
and `##MS_PolicyTsqlExecutionLogin##` will be returned in the result set.
1087-
If the `exact_match` parameter is set to true, then only exact matches are accepted and neither of those logins would have been returned.
1088-
This is an optional parameter which will accept a single string or array of strings as input.
1089+
If the `exact_match` parameter is set to true, only exact matches are accepted and neither of those logins would have been returned.
1090+
This is an optional parameter which accepts a single string or array of strings as input.
10891091

10901092
* **exact_match**
10911093

10921094
Set this to true to change the behavior of the `login_name` parameter so that only logins exactly matching one of the provided login_names is returned in the result set.
1093-
This is an optional parameter which will accept either `true` or `false`. It's default value is false.
1095+
This is an optional parameter which accepts either `true` or `false`. It's default value is false.
10941096

10951097
* **detailed**
10961098

1097-
This parameter causes the task to return a more detailed level of information for each login.
1098-
By default the list of properties returned about each login is: `Name`,`isDisabled`,`isLocked`,`IsPasswordExpired`,`CreateDate`,`DateLastModified`.
1099+
This parameter causes the task to return more detailed information for each login.
1100+
By default, the list of properties returned about each login is: `Name`,`isDisabled`,`isLocked`,`IsPasswordExpired`,`CreateDate`,`DateLastModified`.
10991101
Setting this parameter to true adds in the following properties: `DefaultDatabase`,`DenyWindowsLogin`,`HasAccess`,`ID`,`IsSystemObject`,`Language`,`LanguageAlias`,`,LoginType`,`MustChangePassword`,`PasswordExpirationEnabled`,`PasswordHashAlgorithm`,`PasswordPolicyEnforced`,`SQLSID`,`ADSid`,`WindowsLoginAccessType`,`UserData`,`State`,`IsDesignMode`,`InstanceName`
11001102

1101-
> **A note about `SQLSID` and `ADSID`.**
1103+
> **Note about `SQLSID` and `ADSID`.**
11021104
>
11031105
> The `SQLSID` property is this module's property name for the binary representation of a SID that SQLServer keeps internally in tables like `sys.server_principals`.
11041106
> It will look like `0x01` for accounts like `sa`, or something longer like `0x0106000000000009010000005FB6DAC7F7DB546D706711B128B5063888B01770` for other accounts.
11051107
> This `sid` does not look like a normal `sid` you might see outside of SQLServer, but it is returned as part of the detailed information to make it easier to correlate the logins returned by this module and query results from SQLServer.
1106-
> The `ADSID` property is a more normal looking `sid` you might get from PowerShell Active Directory query tools.
1107-
> It is a direct translation of that `SQLSID` into the Microsoft string `sid` form and will look something like `S-1-5-80-1402415987-66678372-3059512406-1823130485-2345841878`.
1108+
> The `ADSID` property is a more normal looking `sid` you might get from PowerShell Active Directory (AD) query tools.
1109+
> It is a direct translation of that `SQLSID` into the Microsoft string `sid` form and looks like `S-1-5-80-1402415987-66678372-3059512406-1823130485-2345841878`.
11081110
> This translation is done to make it easier to correlate SQLServer logins with AD users and detect when something like a user has been disconnected from its real AD SID.
11091111
> If the detailed information for a login does not contain a value for the AD SID property, it means that the login is internal to SQLServer and does not have a valid AD format `sid`.
11101112
@@ -1115,8 +1117,8 @@ Use the `detailed` parameter to return more detailed information including the S
11151117
* **instance_name**
11161118

11171119
The name of the instance to find the login you are setting properties on.
1118-
By default this parameter will use the default instance only.
1119-
Named instances can be referred to by either the short name of the instance, or by `<COMPUTERNAME>\<INSTANCE_NAME>`.
1120+
By default, this parameter only uses the default instance.
1121+
Refer to named instances by either the short name of the instance, or by `<COMPUTERNAME>\<INSTANCE_NAME>`.
11201122
Specifying an instance name will access only that instance. To affect a login on more than one instance,
11211123
specify all of the required instance names as an array of values.
11221124
Pass the values `.`, `MSSQLSERVER`, or the node name to query only the default instance.
@@ -1125,8 +1127,8 @@ Use the `detailed` parameter to return more detailed information including the S
11251127
* **login_name**
11261128

11271129
The name of a particular login to to set properties on.
1128-
By default this parameter expects an exact match. To use pattern matching see the `fuzzy_match` parameter.
1129-
This is an optional parameter which will accept a single string or array of strings as input.
1130+
By default, this parameter expects an exact match. To use pattern matching see the `fuzzy_match` parameter.
1131+
This is an optional parameter which accepts a single string or array of strings as input.
11301132

11311133
* **fuzzy_match**
11321134

@@ -1135,31 +1137,29 @@ Use the `detailed` parameter to return more detailed information including the S
11351137
For example, if the string `sql` is passed to the `login_name` parameter, while `fuzzy_match` is set to true, logins such as `NT SERVICE\SQLWriter`
11361138
and `##MS_PolicyTsqlExecutionLogin##` will be returned in the result set.
11371139
This is an
1138-
optional parameter which will accept either `true` or `false`. Its default value is false.
1140+
optional parameter which accepts either `true` or `false`. Its default value is false.
11391141

11401142
* **enabled**
11411143

1142-
Set this parameter to true to enable a login and set to false to disable it.
1144+
Set this parameter to true to enable a login. Set to false to disable it.
11431145
This is an optional boolean parameter. The return value will be an element in the json return
11441146
specifying that the new value for the `isDisabled` property of the login object will be either `true` or `false`.
11451147

11461148
* **password**
11471149

11481150
Provide a value specifying the new password to use for a login.
1149-
Please note that there are possible string parsing issues when using this parameter.
1150-
For instance attempting to set a password `'pa$ssword#"'` may not parse correctly.
1151-
To get the double quote to end up in the password correctly you will need to triple quote escape the double quote,
1152-
like so `'pa$ssword#"""'`.
1153-
To ensure you password is interpreted and set correctly you may want to try to echo the password out using `bolt command run` first
1154-
to ensure the characters end up on the target node correctly like so, `bolt command run 'Write-Host ''This is """awesome""".'''`
1151+
Note that there are possible string parsing issues when using this parameter.
1152+
For example, attempting to set a password `'pa$ssword#"'` may not parse correctly.
1153+
To get the double quote to end up in the password correctly, triple quote escape the double quote,
1154+
for example, `'pa$ssword#"""'`.
1155+
To ensure your password is interpreted and set correctly, try to echo the password out using `bolt command run` first to ensure that the characters end up on the target node correctly, for example, `bolt command run 'Write-Host ''This is """awesome""".'''`
11551156

11561157
##### noop
11571158

11581159
This task supports the `--noop` flag. The task will return json values indicating the
11591160
actions it would have taken and the logins it would have affected without actually taking any action.
11601161
It will not inspect and return to you what the state of a property was before taking the action.
1161-
Use this parameter especially when using the `fuzzy_match` parameter to ensure you are affecting
1162-
only the logins you intend to.
1162+
Use this parameter — especially when using the `fuzzy_match` parameter — to ensure that you are affecting only the logins you intend to.
11631163

11641164
#### sqlserver::get_sqlagent_jobs
11651165

@@ -1168,19 +1168,19 @@ only the logins you intend to.
11681168
* **instance_name**
11691169

11701170
The name of the instance to get job information from. Leave this variable blank to return information from all instances by default.
1171-
Named instances can be referred to by either the short name of the instance, or by `<COMPUTERNAME>\<INSTANCE_NAME>`. Specifying an instance name will access only that instance.
1171+
Refer to named instances by either the short name of the instance or by `<COMPUTERNAME>\<INSTANCE_NAME>`. Specifying an instance name will access only that instance.
11721172
Pass the values `.`, `MSSQLSERVER`, or the node name to query only the default instance.
1173-
This is an optional parameter which will accept a single string or array of strings as input.
1173+
This is an optional parameter which accepts a single string or array of strings as input.
11741174

11751175
* **job_name**
11761176

1177-
The name of a job, or the pattern to match on a jobs name.
1178-
This is an optional parameter which will accept a single string or array of strings as input.
1177+
The name of a job, or the pattern, to match on a jobs name.
1178+
This is an optional parameter which accepts a single string or array of strings as input.
11791179

11801180
* **exact_match**
11811181

11821182
Set this to true to change the behavior of the `job_name` parameter so that only jobs with names exactly matching one of the provided job_names is returned in the result set.
1183-
This is an optional parameter which will accept either `true` or `false`. It's default value is false.
1183+
This is an optional parameter which accepts either `true` or `false`. It's default value is false.
11841184

11851185
### Microsoft SQL Server terms
11861186

0 commit comments

Comments
 (0)