Lokasi ngalangkungan proxy:   [ UP ]  
[Ngawartoskeun bug]   [Panyetelan cookie]                
Skip to content

Commit 70c0540

Browse files
rwestMSFTrwestMSFT
committed
SQL Assessment for Linux
This is a demo
1 parent 3766a87 commit 70c0540

3 files changed

Lines changed: 269 additions & 0 deletions

File tree

‎docs/linux/media/tutorial-sql-assessment-api/azure-data-studio-extension.png‎

143 KB
Loading

‎docs/linux/sql-server-linux-sql-assessment-api.md‎

Lines changed: 267 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,267 @@
1+
---
2+
title: Use SQL Assessment API for SQL Server on Linux
3+
description: This article describes how to run the SQL Assessment API for SQL Server on Linux and containers.
4+
author: aravindmahadevan-ms
5+
ms.author: armaha
6+
ms.reviewer: amitkh-msft, randolphwest
7+
ms.date: 01/17/2023
8+
ms.service: sql
9+
ms.subservice: linux
10+
ms.topic: conceptual
11+
---
12+
# Use SQL Assessment API for SQL Server on Linux
13+
14+
[!INCLUDE [SQL Server - Linux](../includes/applies-to-version/sql-linux.md)]
15+
16+
The [SQL Assessment API](../tools/sql-assessment-api/sql-assessment-api-overview.md) provides a mechanism to evaluate configuration of [!INCLUDE [ssnoversion-md](../includes/ssnoversion-md.md)] for best practices. The API is delivered with a ruleset containing best practices recommended by the [!INCLUDE [ssnoversion-md](../includes/ssnoversion-md.md)] team. This ruleset is enhanced with the release of new versions. It is useful to make sure your [!INCLUDE [ssnoversion-md](../includes/ssnoversion-md.md)] configuration is in line with the recommended best practices.
17+
18+
The Microsoft's shipped ruleset is available on GitHub. You can view the [entire ruleset](https://github.com/microsoft/sql-server-samples/blob/567d49a42d4cf10e4942b19290ab80828b451b77/samples/manage/sql-assessment-api/DefaultRuleset.csv) in the [samples repository](https://aka.ms/sql-assessment-api).
19+
20+
In this article, we look at two ways to run the SQL Assessment API for [!INCLUDE [ssnoversion-md](../includes/ssnoversion-md.md)] on Linux and containers:
21+
22+
- [SQL Assessment extension for Azure Data Studio](#sql-assessment-extension-for-azure-data-studio)
23+
- [SQL Assessment API with PowerShell](#sql-assessment-api-with-powershell)
24+
25+
## SQL Assessment extension for Azure Data Studio
26+
27+
The SQL Assessment extension for Azure Data Studio provides a mechanism to evaluate the configuration of [!INCLUDE [ssnoversion-md](../includes/ssnoversion-md.md)] for best practices.
28+
29+
With this preview version, you can:
30+
31+
- Assess a [!INCLUDE [ssnoversion-md](../includes/ssnoversion-md.md)], Azure SQL database, or Azure SQL Managed Instance and its databases, with built-in rules
32+
- Get a list of all built-in rules applicable to an instance and its databases
33+
- Export assessment results and the list of applicable rules as a script to store it in a SQL table
34+
- Create HTML reports on assessments results
35+
36+
:::image type="content" source="media/tutorial-sql-assessment-api/azure-data-studio-extension.png" alt-text="Screenshot showing the SQL Assessment extension in Azure Data Studio.":::
37+
38+
### Start a SQL Assessment
39+
40+
- After you install the SQL Assessment extension, expand your server list, right-click a server or database that you want to assess, and select **Manage**.
41+
- Then, in the General section, select **SQL Assessment**. On the Assessment tab, select **Invoke Assessment** to perform assessment of the selected SQL Server or Azure SQL database. Once the results are available, you can use the filtering and sorting features.
42+
- Select **Export as Script** to get the results in an insert-into-table format. You can also select **Create HTML Report** to save the assessment results as an HTML file. Some assessment rules are intended for particular [!INCLUDE [ssnoversion-md](../includes/ssnoversion-md.md)] configurations and some for others. The same is true for database rules. For example, there are rules that are applicable only to [!INCLUDE [sssql16-md](../includes/sssql16-md.md)] or the `tempdb` database.
43+
- The **View applicable rules** button displays the assessment rules that are used to perform assessment of your servers and databases after you select **Invoke Assessment**. To view information about [!INCLUDE [ssnoversion-md](../includes/ssnoversion-md.md)] and SQL Assessment API, select **Info**. Assessment session results can be reviewed on the History tab.
44+
45+
## SQL Assessment API with PowerShell
46+
47+
A second option is to use PowerShell to run the SQL Assessment API script.
48+
49+
### Prerequisites
50+
51+
1. Make sure that you have [installed PowerShell on Linux](/powershell/scripting/install/installing-powershell-on-linux).
52+
53+
1. Install the `SqlServer` PowerShell module from the PowerShell Gallery, running as the `mssql` user.
54+
55+
```bash
56+
su mssql -c "/usr/bin/pwsh -Command Install-Module SqlServer"
57+
```
58+
59+
### Set up the assessment
60+
61+
The SQL Assessment API output is available in JSON format. You will need to take the following steps to configure the SQL Assessment API as follows:
62+
63+
1. In the instance you wish to assess, create a login for SQL Server assessments using SQL Authentication. You can use the following Transact-SQL (T-SQL) script to create a login and strong password. Replace `<*PASSWORD*>` with a strong password of your choosing.
64+
65+
```sql
66+
USE [master];
67+
GO
68+
69+
CREATE LOGIN [assessmentLogin] WITH PASSWORD = N'<*PASSWORD*>';
70+
ALTER SERVER ROLE [CONTROL SERVER] ADD MEMBER [assessmentLogin];
71+
GO
72+
```
73+
74+
The **CONTROL SERVER** role works for most of the assessments. However, there are a few assessments that might need **sysadmin** privileges. If you aren't running those rules, we recommend using **CONTROL SERVER** permissions.
75+
76+
1. Store the credentials for login on the system as follows, again replacing `<*PASSWORD*>` with the password you used in the previous step.
77+
78+
```bash
79+
echo "assessmentLogin" > /var/opt/mssql/secrets/assessment
80+
echo "<*PASSWORD*>" >> /var/opt/mssql/secrets/assessment
81+
```
82+
83+
1. Secure the new assessment credentials by ensuring that only the `mssql` user can access the credentials.
84+
85+
```bash
86+
chmod 600 /var/opt/mssql/secrets/assessment
87+
chown mssql:mssql /var/opt/mssql/secrets/assessment
88+
```
89+
90+
### Download the assessment script
91+
92+
Following is a sample script that calls the SQL Assessment API, using the credentials created in the preceding steps. The script will generate an output file in JSON format at this location: `/var/opt/mssql/log/assessments`.
93+
94+
> [!NOTE]
95+
> The SQL Assessment API can also generate output in CSV and XML formats.
96+
97+
This script is available for download from [GitHub](https://github.com/microsoft/sql-server-samples/blob/master/samples/manage/sql-assessment-api/RHEL/runassessment.ps1).
98+
99+
You can save this file as `/opt/mssql/bin/runassessment.ps1`.
100+
101+
```powershell
102+
[CmdletBinding()] param ()
103+
$Error.Clear()
104+
# Create output directory if not exists
105+
$outDir = '/var/opt/mssql/log/assessments'
106+
if (-not ( Test-Path $outDir )) { mkdir $outDir }
107+
$outPath = Join-Path $outDir 'assessment-latest'
108+
$errorPath = Join-Path $outDir 'assessment-latest-errors'
109+
if ( Test-Path $errorPath ) { remove-item $errorPath }
110+
function ConvertTo-LogOutput {
111+
[CmdletBinding()]
112+
param (
113+
[Parameter(ValueFromPipeline = $true)]
114+
$input
115+
)
116+
process {
117+
switch ($input) {
118+
{ $_ -is [System.Management.Automation.WarningRecord] } {
119+
$result = @{
120+
'TimeStamp' = $(Get-Date).ToString("O");
121+
'Warning' = $_.Message
122+
}
123+
}
124+
default {
125+
$result = @{
126+
'TimeStamp' = $input.TimeStamp;
127+
'Severity' = $input.Severity;
128+
'TargetType' = $input.TargetType;
129+
'ServerName' = $serverName;
130+
'HostName' = $hostName;
131+
'TargetName' = $input.TargetObject.Name;
132+
'TargetPath' = $input.TargetPath;
133+
'CheckId' = $input.Check.Id;
134+
'CheckName' = $input.Check.DisplayName;
135+
'Message' = $input.Message;
136+
'RulesetName' = $input.Check.OriginName;
137+
'RulesetVersion' = $input.Check.OriginVersion.ToString();
138+
'HelpLink' = $input.HelpLink
139+
}
140+
141+
if ( $input.TargetType -eq 'Database') {
142+
$result['AvailabilityGroup'] = $input.TargetObject.AvailabilityGroupName
143+
}
144+
}
145+
}
146+
147+
$result
148+
}
149+
}
150+
151+
function Get-TargetsRecursive {
152+
153+
[CmdletBinding()]
154+
Param (
155+
[Parameter(ValueFromPipeline = $true)]
156+
[Microsoft.SqlServer.Management.Smo.Server] $server
157+
)
158+
159+
$server
160+
$server.Databases
161+
}
162+
163+
function Get-ConfSetting {
164+
[CmdletBinding()]
165+
param (
166+
$confFile,
167+
$section,
168+
$name,
169+
$defaultValue = $null
170+
)
171+
172+
$inSection = $false
173+
174+
switch -regex -file $confFile {
175+
"^\s*\[\s*(.+?)\s*\]" {
176+
$inSection = $matches[1] -eq $section
177+
}
178+
"^\s*$($name)\s*=\s*(.+?)\s*$" {
179+
if ($inSection) {
180+
return $matches[1]
181+
}
182+
}
183+
}
184+
185+
return $defaultValue
186+
}
187+
188+
try {
189+
190+
Write-Verbose "Acquiring credentials"
191+
192+
$login, $pwd = Get-Content '/var/opt/mssql/secrets/assessment' -Encoding UTF8NoBOM -TotalCount 2
193+
$securePassword = ConvertTo-SecureString $pwd -AsPlainText -Force
194+
$credential = New-Object System.Management.Automation.PSCredential ($login, $securePassword)
195+
196+
Write-Verbose "Acquired credentials"
197+
198+
$serverInstance = '.'
199+
200+
if (Test-Path /var/opt/mssql/mssql.conf) {
201+
$port = Get-ConfSetting /var/opt/mssql/mssql.conf network tcpport
202+
203+
if (-not [string]::IsNullOrWhiteSpace($port)) {
204+
Write-Verbose "Using port $($port)"
205+
$serverInstance = "$($serverInstance),$($port)"
206+
}
207+
}
208+
209+
$serverName = (Invoke-SqlCmd -ServerInstance $serverInstance -Credential $credential -Query "SELECT @@SERVERNAME")[0]
210+
$hostName = (Invoke-SqlCmd -ServerInstance $serverInstance -Credential $credential -Query "SELECT HOST_NAME()")[0]
211+
212+
# Invoke assessment and store results.
213+
# Replace 'ConvertTo-Json' with 'ConvertTo-Csv' to change output format.
214+
# Available output formats: JSON, CSV, XML.
215+
# Encoding parameter is optional.
216+
217+
Get-SqlInstance -ServerInstance $serverInstance -Credential $credential -ErrorAction Stop
218+
| Get-TargetsRecursive
219+
| % { Write-Verbose "Invoke assessment on $($_.Urn)"; $_ }
220+
| Invoke-SqlAssessment 3>&1
221+
| ConvertTo-LogOutput
222+
| ConvertTo-Json -AsArray
223+
| Set-Content $outPath -Encoding UTF8NoBOM
224+
}
225+
finally {
226+
227+
Write-Verbose "Error count: $($Error.Count)"
228+
229+
if ($Error) {
230+
$Error
231+
| ForEach-Object { @{ 'TimeStamp' = $(Get-Date).ToString("O"); 'Message' = $_.ToString() } }
232+
| ConvertTo-Json -AsArray
233+
| Set-Content $errorPath -Encoding UTF8NoBOM
234+
}
235+
}
236+
```
237+
238+
### Run the assessment
239+
240+
1. Make sure the script is owned and executable by `mssql`.
241+
242+
```bash
243+
chown mssql:mssql /opt/mssql/bin/runassessment.ps1
244+
chmod 700 /opt/mssql/bin/runassessment.ps1
245+
```
246+
247+
1. Create log folder and assign appropriate permissions to the `mssql` user on the folder:
248+
249+
```bash
250+
mkdir /var/opt/mssql/log/assessments/
251+
chown mssql:mssql /var/opt/mssql/log/assessments/
252+
chmod 0700 /var/opt/mssql/log/assessments/
253+
```
254+
255+
1. You can now create your first assessment, but make sure you do so as the `mssql` user, so that subsequent assessments can be run automatically via `cron` or `systemd` more securely.
256+
257+
```bash
258+
su mssql -c "pwsh -File /opt/mssql/bin/runassessment.ps1"
259+
```
260+
261+
1. Once the command completes, the output will be generated in JSON format. This output can be integrated with any third party tool that supports parsing JSON files. One such example tool is [RedHat Insights](https://www.redhat.com/en/blog/sql-server-database-best-practices-now-available-through-red-hat-insights).
262+
263+
## Next steps
264+
265+
- [SQL Assessment API](../tools/sql-assessment-api/sql-assessment-api-overview.md)
266+
- [SQL best practices assessment for SQL Server on Azure VMs](/azure/azure-sql/virtual-machines/windows/sql-assessment-for-sql-vm)
267+
- [Vulnerability assessment for SQL Server](../relational-databases/security/sql-vulnerability-assessment.md)

‎docs/toc.yml‎

Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -10360,6 +10360,8 @@ items:
1036010360
href: linux/sample-unattended-install-suse.md
1036110361
- name: Ubuntu
1036210362
href: linux/sample-unattended-install-ubuntu.md
10363+
- name: SQL Assessment API
10364+
href: linux/sql-server-linux-sql-assessment-api.md
1036310365
- name: Resources
1036410366
items:
1036510367
- name: Troubleshoot

0 commit comments

Comments
 (0)