diff --git a/.github/workflows/AutoLabelAssign.yml b/.github/workflows/AutoLabelAssign.yml new file mode 100644 index 0000000000..1a30efad7c --- /dev/null +++ b/.github/workflows/AutoLabelAssign.yml @@ -0,0 +1,35 @@ +name: Assign and label PR + +permissions: + pull-requests: write + contents: read + actions: read + +on: + workflow_run: + workflows: [Background tasks] + types: + - completed + +jobs: + download-payload: + name: Download and extract payload artifact + uses: MicrosoftDocs/microsoft-365-docs/.github/workflows/Shared-ExtractPayload.yml@workflows-prod + with: + WorkflowId: ${{ github.event.workflow_run.id }} + OrgRepo: ${{ github.repository }} + secrets: + AccessToken: ${{ secrets.GITHUB_TOKEN }} + + label-assign: + name: Run assign and label + needs: [download-payload] + uses: MicrosoftDocs/microsoft-365-docs/.github/workflows/Shared-AutoLabelAssign.yml@workflows-prod + with: + PayloadJson: ${{ needs.download-payload.outputs.WorkflowPayload }} + AutoAssignUsers: 1 + AutoLabel: 1 + ExcludedUserList: '["user1", "user2"]' + ExcludedBranchList: '["branch1", "branch2"]' + secrets: + AccessToken: ${{ secrets.GITHUB_TOKEN }} diff --git a/.github/workflows/AutoLabelMsftContributor.yml b/.github/workflows/AutoLabelMsftContributor.yml new file mode 100644 index 0000000000..7058a420cf --- /dev/null +++ b/.github/workflows/AutoLabelMsftContributor.yml @@ -0,0 +1,34 @@ +name: Auto label Microsoft contributors + +permissions: + pull-requests: write + contents: read + actions: read + +on: + workflow_run: + workflows: [Background tasks] + types: + - completed + +jobs: + download-payload: + if: github.repository_visibility == 'public' + name: Download and extract payload artifact + uses: MicrosoftDocs/microsoft-365-docs/.github/workflows/Shared-ExtractPayload.yml@workflows-prod + with: + WorkflowId: ${{ github.event.workflow_run.id }} + OrgRepo: ${{ github.repository }} + secrets: + AccessToken: ${{ secrets.GITHUB_TOKEN }} + + label-msft: + name: Label Microsoft contributors + if: github.repository_visibility == 'public' + needs: [download-payload] + uses: MicrosoftDocs/microsoft-365-docs/.github/workflows/Shared-AutoLabelMsftContributor.yml@workflows-prod + with: + PayloadJson: ${{ needs.download-payload.outputs.WorkflowPayload }} + secrets: + AccessToken: ${{ secrets.GITHUB_TOKEN }} + TeamReadAccessToken: ${{ secrets.ORG_READTEAMS_TOKEN }} diff --git a/.github/workflows/BackgroundTasks.yml b/.github/workflows/BackgroundTasks.yml new file mode 100644 index 0000000000..c0389bb252 --- /dev/null +++ b/.github/workflows/BackgroundTasks.yml @@ -0,0 +1,26 @@ +name: Background tasks + +permissions: + pull-requests: write + contents: read + +on: + pull_request_target: + +jobs: + upload: + runs-on: ubuntu-latest + + steps: + - name: Save payload data + env: + PayloadJson: ${{ toJSON(github) }} + AccessToken: ${{ github.token }} + run: | + mkdir -p ./pr + echo $PayloadJson > ./pr/PayloadJson.json + sed -i -e "s/$AccessToken/XYZ/g" ./pr/PayloadJson.json + - uses: actions/upload-artifact@v4 + with: + name: PayloadJson + path: pr/ diff --git a/.github/workflows/LiveMergeCheck.yml b/.github/workflows/LiveMergeCheck.yml new file mode 100644 index 0000000000..56b79b4813 --- /dev/null +++ b/.github/workflows/LiveMergeCheck.yml @@ -0,0 +1,19 @@ +name: PR can merge into branch + +permissions: + pull-requests: write + statuses: write + contents: read + +on: + pull_request_target: + types: [opened, reopened, synchronize, edited] + +jobs: + + live-merge: + uses: MicrosoftDocs/microsoft-365-docs/.github/workflows/Shared-LiveMergeCheck.yml@workflows-prod + with: + PayloadJson: ${{ toJSON(github) }} + secrets: + AccessToken: ${{ secrets.GITHUB_TOKEN }} diff --git a/.github/workflows/PrFileCount.yml b/.github/workflows/PrFileCount.yml new file mode 100644 index 0000000000..95fcf5e1ed --- /dev/null +++ b/.github/workflows/PrFileCount.yml @@ -0,0 +1,19 @@ +name: PR file count less than limit + +permissions: + pull-requests: write + statuses: write + contents: read + +on: + pull_request_target: + types: [opened, reopened, synchronize, labeled, unlabeled, edited] + +jobs: + + file-count: + uses: MicrosoftDocs/microsoft-365-docs/.github/workflows/Shared-PrFileCount.yml@workflows-prod + with: + PayloadJson: ${{ toJSON(github) }} + secrets: + AccessToken: ${{ secrets.GITHUB_TOKEN }} diff --git a/.github/workflows/ProtectedFiles.yml b/.github/workflows/ProtectedFiles.yml new file mode 100644 index 0000000000..769cd0aa14 --- /dev/null +++ b/.github/workflows/ProtectedFiles.yml @@ -0,0 +1,17 @@ +name: PR has no protected files + +permissions: + pull-requests: write + statuses: write + contents: read + +on: [pull_request_target] + +jobs: + + protected-files: + uses: MicrosoftDocs/microsoft-365-docs/.github/workflows/Shared-ProtectedFiles.yml@workflows-prod + with: + PayloadJson: ${{ toJSON(github) }} + secrets: + AccessToken: ${{ secrets.GITHUB_TOKEN }} diff --git a/.openpublishing.build.ps1 b/.openpublishing.build.ps1 deleted file mode 100644 index aadef76202..0000000000 --- a/.openpublishing.build.ps1 +++ /dev/null @@ -1,17 +0,0 @@ -param( - [string]$buildCorePowershellUrl = "https://opbuildstorageprod.blob.core.windows.net/opps1container/.openpublishing.buildcore.ps1", - [string]$parameters -) -# Main -$errorActionPreference = 'Stop' - -# Step-1: Download buildcore script to local -echo "download build core script to local with source url: $buildCorePowershellUrl" -$repositoryRoot = Split-Path -Parent $MyInvocation.MyCommand.Definition -$buildCorePowershellDestination = "$repositoryRoot\.openpublishing.buildcore.ps1" -Invoke-WebRequest $buildCorePowershellUrl -OutFile "$buildCorePowershellDestination" - -# Step-2: Run build core -echo "run build core script with parameters: $parameters" -& "$buildCorePowershellDestination" "$parameters" -exit $LASTEXITCODE diff --git a/ContentOwners.txt b/ContentOwners.txt new file mode 100644 index 0000000000..e44f0a60e3 --- /dev/null +++ b/ContentOwners.txt @@ -0,0 +1,9 @@ + +# Each line is a file pattern followed by one or more owners. + +# Order is important! The last matching pattern has the most precedence. +# So if a pull request only touches javascript files, only these owners +# will be requested to review. + +/docset/ @roharwoo + diff --git a/TeamsAdmin.png b/TeamsAdmin.png deleted file mode 100644 index 6f0bc278b0..0000000000 Binary files a/TeamsAdmin.png and /dev/null differ diff --git a/cabgen-bootstrap.yml b/cabgen-bootstrap.yml index 51843abfaa..6d83c662c5 100644 --- a/cabgen-bootstrap.yml +++ b/cabgen-bootstrap.yml @@ -5,10 +5,10 @@ pr: none # Disable pull request triggers. resources: repositories: - - repository: templates + - repository: ReferenceAutomation type: git name: Content CI/ReferenceAutomation ref: refs/heads/master extends: - template: PowerShell/cabgen.yml@templates \ No newline at end of file + template: PowerShell/cabgen.yml@ReferenceAutomation diff --git a/docset/docfx.json b/docset/docfx.json index bcd6857d85..dc6f5e5683 100644 --- a/docset/docfx.json +++ b/docset/docfx.json @@ -1,44 +1,44 @@ { "build": { "content": [ - { "files": [ "toc.yml" ], "src": "bread", "dest": "windows/bread" }, + { "dest": "windows/bread", "files": [ "toc.yml" ], "src": "bread" }, - { "files": [ "**/*.md" ], "src": "docs-conceptual/winserver2025-ps", "version": "WindowsServer2025-ps", "dest": "windows" }, - { "files": [ "toc.yml" ], "src": "docs-conceptual/winserver2025-ps", "version": "WindowsServer2025-ps", "dest": "winserver2025-ps" }, - { "files": [ "**/*.yml" ], "exclude": [ "toc.yml" ], "src": "winserver2025-ps", "version": "WindowsServer2025-ps", "dest": "module" }, - { "files": [ "toc.yml" ], "src": "winserver2025-ps", "version": "WindowsServer2025-ps", "dest": "module/WindowsServer2025-ps" }, - - { "files": [ "**/*.md" ], "src": "docs-conceptual/winserver2022-ps", "version": "WindowsServer2022-ps", "dest": "windows" }, - { "files": [ "toc.yml" ], "src": "docs-conceptual/winserver2022-ps", "version": "WindowsServer2022-ps", "dest": "winserver2022-ps" }, - { "files": [ "**/*.yml" ], "exclude": [ "toc.yml" ], "src": "winserver2022-ps", "version": "WindowsServer2022-ps", "dest": "module" }, - { "files": [ "toc.yml" ], "src": "winserver2022-ps", "version": "WindowsServer2022-ps", "dest": "module/WindowsServer2022-ps" }, + { "dest": "windows", "files": [ "**/*.md" ], "src": "docs-conceptual/winserver2025-ps", "version": "WindowsServer2025-ps" }, + { "dest": "winserver2025-ps", "files": [ "toc.yml" ], "src": "docs-conceptual/winserver2025-ps", "version": "WindowsServer2025-ps" }, + { "dest": "module", "exclude": [ "toc.yml" ], "files": [ "**/*.yml", "**/About/*.md" ], "src": "winserver2025-ps", "version": "WindowsServer2025-ps" }, + { "dest": "module/WindowsServer2025-ps", "files": [ "toc.yml" ], "src": "winserver2025-ps", "version": "WindowsServer2025-ps" }, - { "files": [ "**/*.md" ], "src": "docs-conceptual/winserver2019-ps", "version": "WindowsServer2019-ps", "dest": "windows" }, - { "files": [ "toc.yml" ], "src": "docs-conceptual/winserver2019-ps", "version": "WindowsServer2019-ps", "dest": "winserver2019-ps" }, - { "files": [ "**/*.yml" ], "exclude": [ "toc.yml" ], "src": "winserver2019-ps", "version": "WindowsServer2019-ps", "dest": "module" }, - { "files": [ "toc.yml" ], "src": "winserver2019-ps", "version": "WindowsServer2019-ps", "dest": "module/WindowsServer2019-ps" }, + { "dest": "windows", "files": [ "**/*.md" ], "src": "docs-conceptual/winserver2022-ps", "version": "WindowsServer2022-ps" }, + { "dest": "winserver2022-ps", "files": [ "toc.yml" ], "src": "docs-conceptual/winserver2022-ps", "version": "WindowsServer2022-ps" }, + { "dest": "module", "exclude": [ "toc.yml" ], "files": [ "**/*.yml", "**/About/*.md" ], "src": "winserver2022-ps", "version": "WindowsServer2022-ps" }, + { "dest": "module/WindowsServer2022-ps", "files": [ "toc.yml" ], "src": "winserver2022-ps", "version": "WindowsServer2022-ps" }, - { "files": [ "**/*.md" ], "src": "docs-conceptual/winserver2016-ps", "version": "WindowsServer2016-ps", "dest": "windows" }, - { "files": [ "toc.yml" ], "src": "docs-conceptual/winserver2016-ps", "version": "WindowsServer2016-ps", "dest": "windows" }, - { "files": [ "**/*.yml" ], "exclude": [ "toc.yml" ], "src": "winserver2016-ps", "version": "WindowsServer2016-ps", "dest": "module" }, - { "files": [ "toc.yml" ], "src": "winserver2016-ps", "version": "WindowsServer2016-ps", "dest": "module/WindowsServer2016-ps" }, + { "dest": "windows", "files": [ "**/*.md" ], "src": "docs-conceptual/winserver2019-ps", "version": "WindowsServer2019-ps" }, + { "dest": "winserver2019-ps", "files": [ "toc.yml" ], "src": "docs-conceptual/winserver2019-ps", "version": "WindowsServer2019-ps" }, + { "dest": "module", "exclude": [ "toc.yml" ], "files": [ "**/*.yml", "**/About/*.md" ], "src": "winserver2019-ps", "version": "WindowsServer2019-ps" }, + { "dest": "module/WindowsServer2019-ps", "files": [ "toc.yml" ], "src": "winserver2019-ps", "version": "WindowsServer2019-ps" }, - { "files": [ "**/*.md" ], "src": "docs-conceptual/winserver2012-ps", "version": "winserver2012-ps", "dest": "windows" }, - { "files": [ "toc.yml" ], "src": "docs-conceptual/winserver2012-ps", "version": "winserver2012-ps", "dest": "winserver2012-ps" }, - { "files": [ "**/*.yml" ], "exclude": [ "toc.yml" ], "src": "winserver2012-ps", "version": "winserver2012-ps", "dest": "module" }, - { "files": [ "toc.yml" ], "src": "winserver2012-ps", "version": "winserver2012-ps", "dest": "module/winserver2012-ps" }, + { "dest": "windows", "files": [ "**/*.md" ], "src": "docs-conceptual/winserver2016-ps", "version": "WindowsServer2016-ps" }, + { "dest": "windows", "files": [ "toc.yml" ], "src": "docs-conceptual/winserver2016-ps", "version": "WindowsServer2016-ps" }, + { "dest": "module", "exclude": [ "toc.yml" ], "files": [ "**/*.yml", "**/About/*.md" ], "src": "winserver2016-ps", "version": "WindowsServer2016-ps" }, + { "dest": "module/WindowsServer2016-ps", "files": [ "toc.yml" ], "src": "winserver2016-ps", "version": "WindowsServer2016-ps" }, - { "files": [ "**/*.md" ], "src": "docs-conceptual/winserver2012r2-ps", "version": "winserver2012r2-ps", "dest": "windows" }, - { "files": [ "toc.yml" ], "src": "docs-conceptual/winserver2012r2-ps", "version": "winserver2012r2-ps", "dest": "winserver2012r2-ps" }, - { "files": [ "**/*.yml" ], "exclude": [ "toc.yml" ], "src": "winserver2012r2-ps", "version": "winserver2012r2-ps", "dest": "module" }, - { "files": [ "toc.yml" ], "src": "winserver2012r2-ps", "version": "winserver2012r2-ps", "dest": "module/winserver2012r2-ps" }, + { "dest": "windows", "files": [ "**/*.md" ], "src": "docs-conceptual/winserver2012-ps", "version": "winserver2012-ps" }, + { "dest": "winserver2012-ps", "files": [ "toc.yml" ], "src": "docs-conceptual/winserver2012-ps", "version": "winserver2012-ps" }, + { "dest": "module", "exclude": [ "toc.yml" ], "files": [ "**/*.yml", "**/About/*.md" ], "src": "winserver2012-ps", "version": "winserver2012-ps" }, + { "dest": "module/winserver2012-ps", "files": [ "toc.yml" ], "src": "winserver2012-ps", "version": "winserver2012-ps" }, - { "files": [ "**/*.md" ], "src": "docs-conceptual/mdop", "version": "win-mdop2-ps", "dest": "mdop" }, - { "files": [ "toc.yml" ], "src": "docs-conceptual/mdop", "version": "win-mdop2-ps", "dest": "mdop/win-mdop2-ps" }, - { "files": [ "**/*.yml" ], "exclude": [ "toc.yml" ], "src": "mdop", "version": "win-mdop2-ps", "dest": "module" }, - { "files": [ "toc.yml" ], "src": "mdop", "version": "win-mdop2-ps", "dest": "module/win-mdop2-ps" }, + { "dest": "windows", "files": [ "**/*.md" ], "src": "docs-conceptual/winserver2012r2-ps", "version": "winserver2012r2-ps" }, + { "dest": "winserver2012r2-ps", "files": [ "toc.yml" ], "src": "docs-conceptual/winserver2012r2-ps", "version": "winserver2012r2-ps" }, + { "dest": "module", "exclude": [ "toc.yml" ], "files": [ "**/*.yml", "**/About/*.md" ], "src": "winserver2012r2-ps", "version": "winserver2012r2-ps" }, + { "dest": "module/winserver2012r2-ps", "files": [ "toc.yml" ], "src": "winserver2012r2-ps", "version": "winserver2012r2-ps" }, - { "files": [ "**/*.md" ], "src": "virtual-directory-module", "dest": "module" } + { "dest": "mdop", "files": [ "**/*.md" ], "src": "docs-conceptual/mdop", "version": "win-mdop2-ps" }, + { "dest": "mdop/win-mdop2-ps", "files": [ "toc.yml" ], "src": "docs-conceptual/mdop", "version": "win-mdop2-ps" }, + { "dest": "module", "exclude": [ "toc.yml" ], "files": [ "**/*.yml" ], "src": "mdop", "version": "win-mdop2-ps" }, + { "dest": "module/win-mdop2-ps", "files": [ "toc.yml" ], "src": "mdop", "version": "win-mdop2-ps" }, + + { "dest": "module", "files": [ "**/*.md" ], "src": "virtual-directory-module" } ], "resource": [ { "files": [ "**/*.png", "**/*.jpg" ], "exclude": [ "**/obj/**", "**/includes/**" ] } @@ -91,7 +91,7 @@ "garycentric", "AngelaMotherofDragons", "dstrome", - "v-dihans", + "v-dihans", "sdwheeler", "Stacyrch140", "v-stsavell", diff --git a/docset/images/compare-changes.png b/docset/images/compare-changes.png deleted file mode 100644 index 0d86db70f5..0000000000 Binary files a/docset/images/compare-changes.png and /dev/null differ diff --git a/docset/images/contribute-link.png b/docset/images/contribute-link.png deleted file mode 100644 index 6b17e6dd56..0000000000 Binary files a/docset/images/contribute-link.png and /dev/null differ diff --git a/docset/images/pencil-icon.png b/docset/images/pencil-icon.png deleted file mode 100644 index 82fe7852dd..0000000000 Binary files a/docset/images/pencil-icon.png and /dev/null differ diff --git a/docset/images/preview-changes.png b/docset/images/preview-changes.png deleted file mode 100644 index f98b2c6443..0000000000 Binary files a/docset/images/preview-changes.png and /dev/null differ diff --git a/docset/images/propose-file-change.png b/docset/images/propose-file-change.png deleted file mode 100644 index aedbc07b16..0000000000 Binary files a/docset/images/propose-file-change.png and /dev/null differ diff --git a/docset/winserver2012-ps/activedirectory/About/About.md b/docset/winserver2012-ps/activedirectory/About/About.md new file mode 100644 index 0000000000..449df28850 --- /dev/null +++ b/docset/winserver2012-ps/activedirectory/About/About.md @@ -0,0 +1,26 @@ +--- +description: About articles for the ActiveDirectory module. +Help Version: 3.1.0.0 +Locale: en-US +ms.date: 07/03/2024 +title: About articles +--- +# About topics + +## Description + +About topics cover a range of concepts about PowerShell. + +## About Topics + +### [about_ActiveDirectory](about_ActiveDirectory.md) +The Active Directory module is a command line interface for managing Active Directory. + +### [about_ActiveDirectory_Filter](about_ActiveDirectory_Filter.md) +Describes the syntax and behavior of the search filter supported by the Active Directory module for Windows PowerShell. + +### [about_ActiveDirectory_Identity](about_ActiveDirectory_Identity.md) +The Active Directory module for Windows PowerShell objects have a range of identifying attributes that are used for search and retrieval. + +### [about_ActiveDirectory_ObjectModel](about_ActiveDirectory_ObjectModel.md) +Describes the object model of the Active Directory module for Windows PowerShell. diff --git a/docset/winserver2012-ps/activedirectory/About/about_ActiveDirectory.md b/docset/winserver2012-ps/activedirectory/About/about_ActiveDirectory.md new file mode 100644 index 0000000000..1b7183dcd2 --- /dev/null +++ b/docset/winserver2012-ps/activedirectory/About/about_ActiveDirectory.md @@ -0,0 +1,81 @@ +--- +title: about_ActiveDirectory +ms.date: 04/22/2013 +description: The Active Directory module is a command line interface for managing Active Directory. +Locale: en-US +schema: 2.0.0 +--- + +# about_ActiveDirectory + +## SHORT DESCRIPTION + +The Active Directory module is a command line interface for managing Active +Directory. + +## LONG DESCRIPTION + +The Active Directory module for Windows PowerShell is for IT Professionals who +are administering and interfacing with Active Directory. The Active Directory +module provides an efficient way to complete many administrative, +configuration, and diagnostic tasks across Active Directory Domain Services (AD +DS) and Active Directory Lightweight Directory Services (AD LDS) instances in +their environments. The Active Directory module includes a set of Windows +PowerShell cmdlets and a provider. The provider exposes the Active Directory +database through a hierarchical navigation system, which is very similar to the +file system. As with drives in a file system, such as C:, you can connect +Windows PowerShell drives to Active Directory domains and AD LDS, as well as +Active Directory snapshots. + +### Coverage of Active Directory Module Cmdlets + +Create, Read, Update, and Delete actions are supported for Active Directory +objects by cmdlets such as `New-ADUser`, `Get-ADOrganizationalUnit`, +`Set-ADComputer`, and `Remove-ADUser`. + +Account and Password Policy Management are supported by cmdlets such as +`Enable-ADAccount`, `Unlock-ADAccount`, `New-ADServiceAccount`, +`Set-ADAccountControl`, and `Remove-ADFineGrainedPasswordPolicy`. + +Domain and Forest Management is supported by cmdlets such as `Get-ADForest`, +`Set-ADForest`, `Set-ADForestMode`, `Enable-ADOptionalFeature`, +`Get-ADDomainController`, and `Get-ADDomain`. + +### Listing the Active Directory Module Cmdlets + +To get a list of all of the Active Directory module cmdlets, run + +```powershell +Get-Command -Module ActiveDirectory +``` + +### Getting Started + +Getting started with the Active Directory module for Windows PowerShell is as +easy as clicking the following shortcut: + +Run the following command in any Windows PowerShell prompt to import the Active +Directory module: + +```powershell +Import-Module ActiveDirectory +``` + +### Overview and Conceptual Topics + +The first two of these topics offer a high level overview of the Active +Directory module and the Active Directory Provider. + +- For a brief introduction to the Active Directory provider for Windows + PowerShell, see [ActiveDirectory](/powershell/module/activedirectory). +- The following topics are conceptual support topics for the Active Directory + module cmdlets. + - For an introduction to the **Identity** parameter, which is used by the + Active Directory module cmdlets to identify objects in the directory, see + [about_ActiveDirectory_Identity](about_ActiveDirectory_Identity.md). + - For an introduction to the **Filter** parameter which is used by Active + Directory module cmdlets to search for objects in the directory, see + [about_ActiveDirectory_Filter](about_ActiveDirectory_Filter.md). + - For an introduction to the .NET Framework-based object model implemented by + the Active Directory module, see + [about_ActiveDirectory_ObjectModel](about_ActiveDirectory_ObjectModel.md). diff --git a/docset/winserver2012-ps/activedirectory/About/about_ActiveDirectory_Filter.md b/docset/winserver2012-ps/activedirectory/About/about_ActiveDirectory_Filter.md new file mode 100644 index 0000000000..23a83c0a0a --- /dev/null +++ b/docset/winserver2012-ps/activedirectory/About/about_ActiveDirectory_Filter.md @@ -0,0 +1,351 @@ +--- +title: about_ActiveDirectory_Filter +ms.date: 04/22/2013 +description: Describes the syntax and behavior of the search filter supported by the Active Directory module for Windows PowerShell. +Locale: en-US +schema: 2.0.0 +--- + +# about_ActiveDirectory_Filter + +## SHORT DESCRIPTION + +Describes the syntax and behavior of the search filter supported by the Active +Directory module for Windows PowerShell. + +## LONG DESCRIPTION + +Most get-AD* Active Directory module cmdlets use the Filter parameter to search +for objects. The Filter parameter has been implemented to replace the function +of the LDAP Filter and adds support for PowerShell variables, rich data types, +improved error checking and an Active Directory extended form of the PowerShell +Expression Language. + + +- Support for LDAP Filter Syntax + + The LDAP filter syntax is supported through the **LDAPFilter** parameter. You + will find LDAP filter examples along with the new Active Directory module + filter examples in the Filter Examples section of this topic. + + +- Search Breadth and Depth + + The breadth and depth of your filter-driven search can be modified by two + Active Directory module cmdlet parameters: **SearchBase** and **SearchScope**. + + When within the context of the Active Directory provider, if the + **Searchbase** parameter is not specified, **SearchBase** will default to the + current path. When not running under the Active Directory provider, the + **SearchBase** will default to the server's **DefaultNamingContext**. + + The **SearchScope** parameter defaults to the value `Subtree`, of the + enumerated type **ADSearchScope**. + + For more information, see the **SearchBase** and **SearchScope** parameter + descriptions on any `Get-AD*` cmdlet. + +- Search Result Behavior + + The behavior of the Active Directory module when returning results of a + search is modified by two cmdlet parameters: **ResultPageSize** and + **ResultSetSize**. + + **ResultSetSize** controls the maximum number of returned objects. + + **ResultPageSize** specifies the maximum number of objects for each returned + page of information. + + See the **ResultPageSize** and **ResultSetSize** parameter descriptions on + any `Get-AD*` cmdlet for more information. + + +- Timeout Behavior + + The following statements specify timeout conditions within the Active + Directory module and describe what can be done about a timeout them. + + The default Active Directory module timeout for all operations is 2 + minutes. + + For search operation, the Active Directory module uses paging control + with a 2-minute timeout for each page search. + + > [!NOTE] + > Because a search may involve multiple server page requests the overall + > search time may exceed 2 minutes. + + A **TimeoutException** error indicates that a timeout has occurred. + + For a search operation, you can choose to use a smaller page size, set with + the **ResultPageSize** parameter, if you are getting a **TimeoutException** + error. + + If after trying these changes you are still getting a **TimeoutException** + error, consider optimizing your filter using the guidance in the + Optimizing Filters section of this topic. + + +- Optimizing Filters + + You can enhance the search filter behavior by using these guidelines. + + - Avoid using the **Recursive** parameter as it intensifies resource usage of + the search operation. + - Avoid using bitwise AND operators and bitwise OR operators. For more + information, see the Supported Operators section of this topic. + - Avoid using the logical NOT operator. + - Break down your search into multiple queries with narrower conditions. + + For a full description of filter syntax and usage, see the Filter Syntax + section of this topic. + + +## Filter Examples + +The following section shows many examples of filter use in common queries. + +### Example 1 - Get all entries: + +- LDAP Filter Equivalent: `(objectClass=*)` + +```powershell +Get-ADObject -Filter 'ObjectClass -like "*"' +``` + +### Example 2 - Get entries containing "bob" somewhere in the common name + +- LDAP Filter Equivalent: `(cn=*bob*)` + +```powershell +Get-ADObject -Filter 'CN -like "*bob*"' +``` + +### Example 3 - Get entries with a bad password count greater than five + +- LDAP Filter Equivalent: `(&(!badpwdcount<=5)(badpwdcount=*))` + +```powershell +Get-ADUser -Filter 'badpwdcount -ge 5' +``` + +### Example 4 - Get all users with an e-mail attribute + +- LDAP Filter Equivalent: `(&(objectClass=user)(email=*))` + +```powershell +Get-ADUser -filter 'email -like "*"' +``` + +-or- + +```powershell +Get-ADObject -filter 'email -like "*" -and ObjectClass -eq "user"' +``` + +### Example 5 - Get all user entries with an e-mail attribute and a surname equal to "smith": + +- LDAP Filter Equivalent: `(&(sn=smith)(objectClass=user)(email=*))` + +```powershell +Get-ADUser -Filter 'Email -like "*" -and SurName -eq "smith"' +``` + +-or- + +```powershell +Get-ADUser -Filter 'Email -like "*" -and sn -eq "smith"' +``` + + +### Example 6 - Get all user entries with a common name that starts with "andy" and users with a common name of "steve" or "margaret" + +- LDAP Filter Equivalent: `(&(objectClass=user) | (cn=andy*)(cn=steve)(cn=margaret))` + +```powershell +Get-ADUser -Filter 'CN -like "andy*" -or CN -eq "steve" -or CN -eq "margaret"' +``` + + +This example demonstrates a more complex logic and the use of precedence +control via parenthesis. + +```powershell +Get-ADObject -Filter 'objectClass -eq "user" -and (CN -like "andy*" -or CN -eq "steve" -or CN -eq "margaret")' +``` + +### Example 7 - Get all entries without an e-mail attribute + +- LDAP Filter Equivalent: `(!(email=*))` + +```powershell +Get-ADUser -Filter '-not Email -like "*"' +``` + +-or- + +```powershell +Get-ADUser -Filter 'Email -notlike "*"' +``` + +### Example 8 - Get all users who did not logon since January 1, 2007 + +- LDAP Filter Equivalent: `(&(lastlogon<=X)(objectClass=user))` where X is + number of 100-nanosecond slices since Jan 1st 1601 + +```powershell +$date = new-object System.DateTime -ArgumentList @(2007,1,1,0,0,0) +Get-ADUser -Filter '-not LastLogon -le $date' +``` + +### Example 9 - Get all users who have logged on in the last 5 days + +- LDAP Filter Equivalent: + + ``` + (&(lastLogon>=128812906535515110) + (objectClass=user)(!(objectClass=computer))) + ``` + +```powershell +$date = (get-date) - (new-timespan -days 5) +Get-ADUser -Filter 'lastLogon -gt $date' +``` + +### Example 10 - Search for group objects that have the ADS_GROUP_TYPE_SECURITY_ENABLED flag set + +- LDAP Filter Equivalent: + `(&(objectCategory=group)(groupType:1.2.840.113556.1.4.803:=2147483648))` + +The following example query string searches for group objects that have the +ADS_GROUP_TYPE_SECURITY_ENABLED flag set. Be aware that the decimal value of +ADS_GROUP_TYPE_SECURITY_ENABLED (0x80000000 = 2147483648) is used for the +comparison value. + +```powershell +Get-ADGroup -filter 'groupType -band 0x80000000' +``` + +### Example 11 - Search the ancestry of an object + +- LDAP Filter Equivalent: + `(memberof:1.2.840.113556.1.4.1941:=(cn=Group1,OU=groupsOU,DC=x)))` + +The LDAP_MATCHING_RULE_IN_CHAIN is a matching rule OID that is designed to +provide a method to look up the ancestry of an object. Many applications using +Active Directory and AD LDS usually work with hierarchical data, which is +ordered by parent-child relationships. Previously, applications performed +transitive group expansion to figure out group membership, which used a lot of +network bandwidth. Applications made multiple round-trips to figure out if an +object fell "in the chain" if a link were traversed through to the end. + +An example of such a query is one designed to check if a user, "user1" is a +member of group "group1". "user1" may not be a direct member of group1. It +could be a member of some other group, which is a member of "group1". + +You would set the base to the user DN and the scope to base, and use the query: + +```powershell +Get-ADUser -Filter 'memberOf -RecursiveMatch "CN=Administrators, CN=Builtin,DC=Fabrikam,DC=com"' -SearchBase "CN=Administrator,CN=Users,DC=Fabrikam,DC=com" +``` + +## Filter Syntax + +The following syntax descriptions use Backus-Naur form to show the PowerShell +Expression Language for the Filter parameter. + +```Syntax + ::= "{" "}" + + ::= | + | + + + ::= | + "(" ")" + + ::= "-eq" | "-le" | "-ge" | "-ne" | "-lt" | "-gt" | + "-approx" | "-bor" | "-band" | "-recursivematch" | "-like" | + "-notlike" + + ::= "-and" | "-or" + + ::= "-not" + + ::= | + +::= < this value will be compared to the object data for + attribute using the specified filter operator +``` + + +## Supported Operators + +The following table shows frequently used search filter operators. + +| Operator | Description | LDAP Equivalent | +| ----------------- | -------------------------------------- | -------------------------- | +| `-eq` | Equal to. Wildcards not supported. | = | +| `-ne` | Not equal to. Wildcards not supported. | !x = y | +| `-approx` | Approximately equal to | ~= | +| `-le` | Lexicographically less than | <= | +| | or equal to | | +| `-lt` | Lexicographically less than | !x >= y | +| `-ge` | Lexicographically greater | >= | +| | than or equal to | | +| `-gt` | Lexicographically greater than | !x <= y | +| | | | +| `-and` | AND | & | +| `-or` | OR | | +| `-not` | NOT | ! | +| `-bor` | Bitwise OR | :1.2.840.113556.1.4.804:= | +| `-band` | Bitwise AND | :1.2.840.113556.1.4.803:= | +| `-recursivematch` | Use LDAP_MATCHING_RULE_IN_CHAIN | :1.2.840.113556.1.4.1941:= | +| `-like` | Similar to `-eq` and supports | = | +| | wildcard comparison. The only | | +| | wildcard character supported is: `*` | | +| `-notlike` | Not like. Supports wild | !x = y | +| | card comparison. | | + +> [!NOTE] +> PowerShell wildcards, other than "*", such as "?" are not supported by the +> **Filter** parameter syntax. + +### Operator Precedence + +The following listing shows the precedence of operators for filters from +highest to lowest. + +- Highest precedence: `-eq`, `-ge`, `-le`, `-approx`, `-band`, `-bor`, + `-recursivematch`, `-ne`, `-like`, `-not`, `-and` +- Lowest precedence: `-or` + +### Special Characters + +The following escape sequence should be used for specifying special characters +in AD Filter STRING data, that is, data enclosed in double or single quotes. + +| ASCII Character | Escape sequence substitute | +| --------------- | --------------------------------------------------- | +| `"` | `` `" `` (This escape sequence is only required if | +| | STRING data is enclosed in double quotes.) | +| `'` | `''` (This escape sequence is only required if | +| | STRING data is enclosed in single quotes.) | +| NUL | `\00` (This is a standard LDAP escape sequence.) | +| `\` | `\5c` (This is a standard LDAP escape sequence.) | + +### LDAP Special Characters + +ADFilter parser will automatically convert all the below characters found in +STRING data, that is data enclosed in " " or ' ' to their LDAP escape sequence. +End users need not know about these LDAP escape sequence. + +| ASCII Character | Escape sequence substitute | +| --------------- | ----------------------------------------------- | +| `*` | `\2a` (Character `*` will only be converted in | +| | -eq and -ne comparisons Users should use | +| | -like and -notlike operators for wildcard | +| | comparison.) | +| `(` | `\28` | +| `)` | `\29` | +| `/` | `\2f` | diff --git a/docset/winserver2012-ps/activedirectory/About/about_ActiveDirectory_Identity.md b/docset/winserver2012-ps/activedirectory/About/about_ActiveDirectory_Identity.md new file mode 100644 index 0000000000..c007277b19 --- /dev/null +++ b/docset/winserver2012-ps/activedirectory/About/about_ActiveDirectory_Identity.md @@ -0,0 +1,196 @@ +--- +title: about_ActiveDirectory_Identity +ms.date: 04/22/2013 +description: This article lists the identifying attributes that are used for search and retrieval supported by the Active Directory module for Windows PowerShell. +Locale: en-US +schema: 2.0.0 +--- + +# about_ActiveDirectory_Identity + +## SHORT DESCRIPTION + +The Active Directory module for Windows PowerShell objects have a range of +identifying attributes that are used for search and retrieval. + +## LONG DESCRIPTION + +In order to identify the objects in Active Directory, each object has +attributes that can be used as identifiers. In the Active Directory module, the +value of the identity of an object can be passed using the Identity parameter. +Each object type has its own set of possible types and values for use by the +Identity parameter. See the detailed description of the Identity parameter of +the given cmdlet for more information about its usage. + +When searching with the Active Directory module cmdlets, the value of the +Identity parameter, along with the values of the Server and Partition +parameters, is used to uniquely identify a single object. The Server parameter +is used to locate which server to connect with. The Partition parameter further +narrows the search to a specific partition. The Identity parameter then +resolves to a single unique object in the partition. + +Note that using the Security Accounts Manager (SAM) Account Name +(**sAMAccountName**) when targeting a global catalog port, you will not find a +user in a different domain if you are using the Identity parameter + +If more than one object is found using identity resolution, the Active +Directory module throws an error. + +For more information about the Server and Partition parameters, see the help +topics for the individual cmdlets where they are used, such as `Get-ADUser`, by +typing: + +```powershell +Get-Help Get-ADUser +``` + +### Objects and Identities + +Each object has a list of attributes that can be used as an identity for that +object. Additionally, if the object inherits from another object, then the +parent object's identities can also be used as the child object's identities. +For more information on the Active Directory object hierarchy, see +[about_ActiveDirectory_ObjectModel](about_ActiveDirectory_ObjectModel.md). + +> [!NOTE] +> For Active Directory Provider cmdlets, only an object's 'Distinguished Name' +> or 'Relative Distinguished Name' can be used as the identity. For a list of +> Active Directory Provider cmdlets, see ActiveDirectory. + +### Identity Attributes + +The following is a list of identity attributes by object type. + +- ADAccount + - Distinguished Name + - GUID (objectGUID) + - Security Identifier (objectSid) + - SAM Account Name (sAMAccountName) + +- ADComputer + - Distinguished Name + - GUID (objectGUID) + - Security Identifier (objectSid) + - Security Accounts Manager Account Name (sAMAccountName) + +- ADDirectoryServer + - Name of the server object (name) + - For AD LDS instances the syntax of a name is `$` + - For other Active Directory instances, use the value of the name property. + - Distinguished Name of the NTDS Settings object + - Distinguished Name of the server object that represents the directory + server. + - GUID (objectGUID) of server object under the configuration partition. + - GUID (objectGUID) of NTDS settings object under the configuration partition + +- ADDomain + - Distinguished Name + - GUID + - Security Identifier + - DNS domain name + - NetBIOS domain name + +- ADDomainController + - GUID (objectGUID) + - IPV4Address + - Global IPV6Address + - DNS Host Name (dNSHostName) + - Name of the server object + - Distinguished Name of the NTDS Settings object + - Distinguished Name of the server object that represents the domain controller + - GUID of NTDS settings object under the configuration partition + - GUID of server object under the configuration partition + - Distinguished Name of the computer object that represents the domain controller. + +- ADFineGrainedPasswordPolicy + - Distinguished Name + - GUID (objectGUID) + - Name (name) + +- ADForest + - Fully qualified domain name + - DNS host name + - NetBIOS name + +- ADGroup + - Distinguished Name + - GUID (objectGUID) + - Security Identifier (objectSid) + - Security Accounts Manager (SAM) Account Name (sAMAccountName) + +- ADObject + - Distinguished Name + - GUID (objectGUID) + +- ADOptionalFeature + - Distinguished Name + - Name (name) + - Feature GUID (featureGUID) + - GUID (objectGUID) + +- ADOrganizationalUnit + - Distinguished Name + - GUID (objectGUID) + +- ADPrincipal + - Distinguished Name + - GUID (objectGUID) + - Security Identifier (objectSid) + - SAM Account Name (sAMAccountName) + +- ADServiceAccount + - Distinguished Name + - GUID (objectGUID) + - Security Identifier (objectSid) + - SAM Account Name (sAMAccountName) + +- ADUser + - Distinguished Name + - GUID (objectGUID) + - Security Identifier (objectSid) + - SAM User Name (sAMUserName) + + +### Identities Formats + +Active Directory module objects have a range of identity attributes. Below is a +list of these, their types and formats. + +- Distinguished Name + - Example: CN=SaraDavis,CN=Europe,CN=Users, DC=corp,DC=contoso,DC=com + +- DNS domain name + - Example: redmond.corp.contoso.com + +- DNS Host Name (dNSHostName) + - Example: corp-DC01.corp.contoso.com + +- Feature GUID (featureGUID) + - Example: 599c3d2e-f72d-4d20-8a88-030d99495f20 + +- Fully qualified domain name + - Example: corp.contoso.com + +- Global IPV6Address + - Example: 2001:4898:0:fff:200:5efe:157.59.132.61 + +- GUID (objectGUID) + - Example: 599c3d2e-f72d-4d20-8a88-030d99495f20 + +- IPV4Address + - Example:157.59.132.61 + +- NetBIOS domain name + - Example: redmond + +- Name of the server object + - Example: corp-DC01$ + +- SAM Account Name (sAMAccountName) + - Example: saradavisreports + +- Security Identifier (objectSid) + - Example: S-1-5-21-3165297888-301567370-576410423-1103 + +- Name + - Example: Recycle Bin Feature diff --git a/docset/winserver2012-ps/activedirectory/About/about_ActiveDirectory_ObjectModel.md b/docset/winserver2012-ps/activedirectory/About/about_ActiveDirectory_ObjectModel.md new file mode 100644 index 0000000000..8535a97464 --- /dev/null +++ b/docset/winserver2012-ps/activedirectory/About/about_ActiveDirectory_ObjectModel.md @@ -0,0 +1,595 @@ +--- +title: about_ActiveDirectory_ObjectModel +ms.date: 04/22/2013 +description: Describes the object model of the Active Directory module for Windows PowerShell. +Locale: en-US +schema: 2.0.0 +--- + +# about_ActiveDirectory_ObjectModel + +## SHORT DESCRIPTION +Describes the object model of the Active Directory module for Windows +PowerShell. + +## LONG DESCRIPTION + +This topic explains the Active Directory module classes and their properties +used to model actual Active Directory attributes. It also outlines the class +hierarchy constructed from its Active Directory counterpart. The object model +establishes a data foundation for all the operations supported by Active +Directory module cmdlets. + +### Class Hierarchy + +The following list shows the class hierarchy defined in the Active Directory +module object model, with class inheritance implied by indentation. This +inheritance model allows for Active Directory cmdlets to accept a range of +object types as input. This means, for example, that the cmdlet +Get-ADPrincipalGroupMembership can accept as input any of the following +objects: ADGroup, ADAccount, ADComputer, ADServiceAccount or ADUser. This works +because of the inheritance model and guarantees that an ADUser object has all +of the properties of an ADPrincipal object. + +``` +ADEntity + ADRootDSE + ADObject + ADFineGrainedPasswordPolicy + ADOptionalFeature + ADOrganizationalUnit + ADPartition + ADDomain + ADPrincipal + ADAccount + ADComputer + ADServiceAccount + ADUser + ADGroup + ADDefaultDomainPasswordPolicy + ADForest + ADDirectoryServer + ADDomainController +``` + +### Active Directory Module Classes + +The following listing shows every Active Directory module class from the class +hierarchy listing. Each class defines a set of properties, some of which are +LDAP attributes that are retrieved by default and some are new properties +created specifically for the Active Directory module. These new properties are +derived from one or more LDAP attributes as outlined in the class listings. + + +- ADEntity - The base level class from which all other classes are derived. + - ADRootDSE - Represents the rootDSE and is derived from ADEntity. An + ADRootDSE may contain the following properties in addition to those + inherited from its parent. + - ConfigurationNamingContext - A property of type System.String, derived + from the directory attribute ConfigurationNamingContext + - CurrentTime - A property of type System.DateTime, derived from the + directory attribute CurrentTime + - DefaultNamingContext - A property of type System.String, derived from the + directory attribute DefaultNamingContext + - DnsHostName - A property of type System.String, derived from the + directory attribute DnsHostName + - DomainControllerFunctionality - A property of type + ADDomainControllerMode, derived from the directory attribute + DomainControllerFunctionality + - DomainFunctionality - A property of type ADDomainMode, derived from the + directory attribute DomainFunctionality + - DsServiceName - A property of type System.String, derived from the + directory attribute DsServiceName + - ForestFunctionality - A property of type ADForestMode, derived from the + directory attribute ForestFunctionality + - GlobalCatalogReady - A property of type System.Boolean, derived from the + directory attribute GlobalCatalogReady + - HighestCommittedUSN - A property of type System.Long, derived from the + directory attribute HighestCommittedUSN + - LdapServiceName - A property of type System.String, derived from the + directory attribute LdapServiceName + - NamingContexts - A property of type System.String, derived from the + directory attribute NamingContexts + - RootDomainNamingContext - A property of type System.String, derived from + the directory attribute RootDomainNamingContext + - SchemaNamingContext - A property of type System.String, derived from the + directory attribute SchemaNamingContext + - ServerName - A property of type System.String, derived from the directory + attribute ServerName + - SubschemaSubentry - A property of type ADObject, derived from the + directory attribute SubschemaSubentry + - SupportedCapabilities - A property of type ADObjectIdentifier, derived + from the directory attribute SupportedCapabilities + - SupportedControl - A property of type ADObjectIdentifier, derived from + the directory attribute SupportedControl + - SupportedLDAPPolicies - A property of type System.String, derived from + the directory attribute SupportedLDAPPolicies + - SupportedLDAPVersion - A property of type System.Int, derived from the + directory attribute SupportedLDAPVersion + - SupportedRootDSEOperations - A property of type + ADPropertyValueCollection, derived from the directory attribute + SupportedRootDSEOperations + - SupportedSASLMechanisms - A property of type System.String, derived from + the directory attribute SupportedSASLMechanisms + - Syncronized - A property of type System.Boolean, derived from the + directory attribute IsSynchronized. + - ADObject - Represents any object in Active Directory and is derived from + ADEntity. An ADObject may contain the following properties in addition to + those inherited from its parent. + - CanonicalName - A property of type System.String, derived from the + directory attribute: canonicalName + - CN - A property of type System.String, derived from the directory + attribute: cn + - Created - A property of type System.DateTime, derived from the directory + attribute: createTimeStamp + - Deleted - A property of type System.Boolean, derived from the directory + attribute: isDeleted + - Description - A property of type System.String, derived from the + directory attribute: description + - DisplayName - A property of type System.String, derived from the + directory attribute: displayName + - DistinguishedName - A property of type System.String, derived from the + directory attribute: distinguishedName + - LastKnownParent - A property of type System.String, derived from the + directory attribute: lastKnownParent + - Modified - A property of type System.DateTime, derived from the directory + attribute: modifyTimeStamp + - Name - A property of type System.String, derived from the directory + attribute: name + - ObjectCategory - A property of type System.String, derived from the + directory attribute: objectCategory + - ObjectClass - A property of type System.String, derived from the + directory attribute: objectClass + - ObjectGUID - A property of type System.Guid, derived from the directory + attribute: objectGUID + - ProtectedFromAccidentalDeletion - A property of type System.Boolean, + derived from the directory attributes: nTSecurityDescriptor, + sdRightsEffective, instanceType, isDeleted + - ADFineGrainedPasswordPolicy Represents a fine grained password policy + object; that is, an AD object of type msDS-PasswordSettings in AD DS and + is derived from ADObject. This class is not supported by AD LDS. An + ADFineGrainedPasswordPolicy may contain the following properties in + addition to those inherited from its parent. + - AppliesTo - A property of type System.String, derived from the + directory attribute: msDS-PSOAppliesTo + - ComplexityEnabled - A property of type System.Boolean, derived from the + directory attribute: msDS-PasswordComplexityEnabled + - LockoutDuration - A property of type System.TimeSpan, derived from the + directory attribute: msDS-LockoutDuration + - LockoutObservationWindow - A property of type System.TimeSpan, derived + from the directory attribute: msDS-LockoutObservationWindow + - LockoutThreshold - A property of type System.Int32, derived from the + directory attribute: msDS-LockoutThreshold + - MaxPasswordAge - A property of type System.TimeSpan, derived from the + directory attribute: msDS-MaximumPasswordAge + - MinPasswordAge - A property of type System.TimeSpan, derived from the + directory attribute: msDS-MinimumPasswordAge + - MinPasswordLength - A property of type System.Int32, derived from the + directory attribute: msDS-MinimumPasswordLength + - PasswordHistoryCount - A property of type System.Int32, derived from + the directory attribute: msDS-PasswordHistoryLength + - Precedence - A property of type System.Int32, derived from the + directory attribute: msDS-PasswordSettingsPrecedence + - ReversibleEncryptionEnabled - A property of type System.Boolean, + derived from the directory attribute: + msDS-PasswordReversibleEncryptionEnabled + - ADOptionalFeature Represents an optional feature, an Active Directory + object of type msDS-OptionalFeature, and is derived from ADObject. An + ADOptionalFeaturemay contain the following properties in addition to + those inherited from its parent. + - EnabledScopes - A property of type System.String, derived from the + directory attribute: msDS-EnabledFeatureBL + - FeatureGUID - A property of type System.Guid, derived from the + directory attribute: msDS-OptionalFeatureGUID + - FeatureScope - A property of type System.Int32, derived from the + directory attribute: msDS-OptionalFeatureFlags + - IsDisableable - A property of type System.Boolean, derived from the + directory attribute: msDS-OptionalFeatureFlags + - RequiredDomainMode - A property of type + Microsoft.ActiveDirectory.Management.ADDomainMode, derived from the + directory attribute: msDS-RequiredDomainBehaviorVersion + - RequiredForestMode - A property of type + Microsoft.ActiveDirectory.Management.ADForestMode, derived from the + directory attribute: msDS-RequiredForestBehaviorVersion + - ADOrganizationalUnit Represents an organizationalUnit (OU) object and is + derived from ADObject. An ADOrganizationalUnit may contain the following + properties in addition to those inherited from its parent. + - City - A property of type System.String, derived from the directory + attribute: l + - Country - A property of type System.String, derived from the directory + attribute: c + - LinkedGroupPolicyObjects - A property of type System.String, derived + from the directory attribute: gpLink. This property is not supported on + AD LDS. + - ManagedBy - A property of type System.String, derived from the + directory attribute: managedBy + - PostalCode - A property of type System.String, derived from the + directory attribute: postalCode + - State - A property of type System.String, derived from the directory + attribute: st + - StreetAddress - A property of type System.String, derived from the + directory attribute: street + - ADPartition - Represents a naming context, Configuration, Schema, Domain + or Application Partition(ND NC) and is derived from ADObject. This class + is not supported by AD LDS. An ADPartition may contain the following + properties in addition to those inherited from its parent. + - DeletedObjectsContainer - A property of type System.String, derived + from the directory attribute: DeletedObjectsContainer + - DNSRoot - A property of type System.String, derived from the directory + attribute: DNSRoot + - LostAndFoundContainer - A property of type System.String, derived from + the directory attribute: LostAndFoundContainer + - QuotasContainer - A property of type System.String, derived from the + directory attribute: QuotasContainer + - ReadOnlyReplicaDirectoryServers - A property of type System.String, + derived from the directory attribute: ReadOnlyReplicaDirectoryServers + - ReplicaDirectoryServers - A property of type System.String, derived + from the directory attribute: ReplicaDirectoryServers + - SubordinateReferences - A property of type System.String, derived from + the directory attribute: SubordinateReferences + - ADDomain - Represents a domain in AD DS or an instance in AD LDS; for + example, an Active Directory object of type domainDNS and is derived + from ADPartition. This class is not supported by AD LDS. An ADDomain + may contain the following properties in addition to those inherited + from its parent. + - AllowedDNSSuffixes - A property of type System.String, derived from + the directory attribute: msDS-AllowedDNSSuffixes + - ChildDomains - A property of type System.String, derived from the + directory attribute: ChildDomains + - ComputersContainer - A property of type System.String, derived from + the directory attribute: ComputersContainer + - DomainControllersContainer - A property of type System.String, + derived from the directory attribute: DomainControllersContainer + - DomainMode - A property of type System.Int32, derived from the + directory attribute: msDS-Behavior-Version + - DomainSID - A property of type + System.Security.Principal.SecurityIdentifier, derived from the + directory attribute: objectSid + - ForeignSecurityPrincipalsContainer - A property of type + System.String, derived from the directory attribute: + ForeignSecurityPrincipalsContainer + - Forest - A property of type System.String, derived from the directory + attribute: Forest + - InfrastructureMaster - A property of type System.String, derived from + the directory attribute: InfrastructureMaster + - LastLogonReplicationInterval - A property of type System.TimeSpan, + derived from the directory attribute: msDS-LogonTimeSyncInterval + - LinkedGroupPolicyObjects - A property of type System.String, derived + from the directory attribute: LinkedGroupPolicyObjects + - ManagedBy - A property of type System.String, derived from the + directory attribute: managedBy + - NetBIOSName - A property of type System.String, derived from the + directory attribute: NetBIOSName + - ParentDomain - A property of type System.String, derived from the + directory attribute: ParentDomain + - PDCEmulator - A property of type System.String, derived from the + directory attribute: PDCEmulator + - RIDMaster - A property of type System.String, derived from the + directory attribute: RIDMaster + - SystemsContainer - A property of type System.String, derived from the + directory attribute: SystemsContainer + - UsersContainer - A property of type System.String, derived from the + directory attribute: UsersContainer + - ADPrincipal - Represents a security principal, which is an Active + Directory object of type user, computer, group or iNetOrgPerson and is + derived from ADObject. An ADPrincipal may contain the following + properties in addition to those inherited from its parent. + - HomePage - A property of type System.String, derived from the + directory attribute: wWWHomePage + - MemberOf - A property of type System.String, derived from the + directory attribute: memberOf + - SamAccountName - A property of type System.String, derived from the + directory attribute: sAMAccountName. This property is not supported + for AD LDS. + - SID - A property of type + System.Security.Principal.SecurityIdentifier, derived from the + directory attribute: objectSid + - SIDHistory - A property of type + System.Security.Principal.SecurityIdentifier, derived from the + directory attribute: sIDHistory. This property is not supported for + AD LDS. + - ADAccount - Represents a security account; that is, an Active + Directory object of type user, computer or iNetOrgPerson and is + derived from ADPrincipal. An ADAccount may contain the following + properties in addition to those inherited from its parent. + - AccountExpirationDate - A property of type System.DateTime, derived + from the directory attribute: accountExpires + - AccountLockoutTime - A property of type System.DateTime, derived + from the directory attribute: lockoutTime + - AccountNotDelegated - A property of type System.Boolean, derived + from the directory attributes: userAccountControl, + msDS-User-Account-Control-Computed. This property is not supported + by AD LDS. + - AllowReversiblePasswordEncryption - A property of type + System.Boolean, for AD DS it is derived from the directory + attribute: userAccountControl; for AD LDS it is derived from the + directory attribute: ms-DS-UserEncryptedTextPasswordAllowed + - BadLogonCount - A property of type System.Int32, derived from the + directory attribute: badPwdCount + - CannotChangePassword - A property of type System.Boolean, derived + from the directory attribute: nTSecurityDescriptor + - Certificates - A property of type + System.Security.Cryptography.X509Certificates.X509Certificate, + derived from the directory attribute: userCertificate + - DoesNotRequirePreAuth - A property of type System.Boolean, derived + from the directory attributes: userAccountControl, + msDS-User-Account-Control-Computed. This property is not supported + by AD LDS. + - Enabled - A property of type System.Boolean, for AD DS it is + derived from the directory attributes: userAccountControl, + msDS-User-Account-Control-Computed; for AD LDS it is derived from + the directory attribute msDS-UserAccountDisabled + - HomedirRequired - A property of type System.Boolean, derived from + the directory attributes: userAccountControl, + msDS-User-Account-Control-Computed. This property is not supported + by AD LDS. + - LastBadPasswordAttempt - A property of type System.DateTime, + derived from the directory attribute: badPasswordTime + - LastLogonDate - A property of type System.DateTime, derived from + the directory attribute: lastLogonTimestamp + - LockedOut - A property of type System.Boolean, for AD DS it is + derived from the directory attributes: userAccountControl, + msDS-User-Account-Control-Computed, lockoutTime; for AD LDS it is + derived from the directory attribute msDS-UserAccountDisabled + - MNSLogonAccount - A property of type System.Boolean, derived from + the directory attributes: userAccountControl, + msDS-User-Account-Control-Computed. This property is not supported + by AD LDS. + - PasswordExpired - A property of type System.Boolean, for AD DS it + is derived from the directory attributes: userAccountControl, + msDS-User-Account-Control-Computed; for AD LDS it is derived from + the directory attribute msDS-UserPasswordExpired + - PasswordLastSet - A property of type System.DateTime, derived from + the directory attribute: pwdLastSet + - PasswordNeverExpires - A property of type System.Boolean, for AD + LDS it is derived from the directory attributes: + userAccountControl, msDS-User-Account-Control-Computed; for AD LDS + it is derived from the directory attribute: + msDS-UserDontExpirePassword + - PasswordNotRequired - A property of type System.Boolean, for AD DS + it is derived from the directory attributes: userAccountControl, + msDS-User-Account-Control-Computed; for AD LDS it is derived from + the directory attribute: ms-DS-UserPasswordNotRequired + - PrimaryGroup - A property of type System.String, derived from the + directory attributes: primaryGroupID, objectSid. This property is + not supported by AD LDS. + - ServicePrincipalNames - A property of type System.String, derived + from the directory attribute: servicePrincipalName. This property + is not supported by AD LDS. + - TrustedForDelegation - A property of type System.Boolean, derived + from the directory attributes: userAccountControl, + msDS-User-Account-Control-Computed. This property is not supported + by AD LDS. + - TrustedToAuthForDelegation - A property of type System.Boolean, + derived from the directory attributes: userAccountControl, + msDS-User-Account-Control-Computed. This property is not supported + by AD LDS. + - UseDESKeyOnly - A property of type System.Boolean, derived from the + directory attributes: userAccountControl, + msDS-User-Account-Control-Computed. This property is not supported + by AD LDS. + - UserPrincipalName - A property of type System.String, derived from + the directory attribute: userPrincipalName + - ADComputer - Represents a computer and is derived from ADAccount. + An ADComputer may contain the following properties in addition to + those inherited from its parent. + - DNSHostName - A property of type System.String, derived from the + directory attribute: dNSHostName + - IPv4Address - A property of type System.String, derived from the + directory attribute: dNSHostName + - IPv6Address - A property of type System.String, derived from the + directory attribute: dNSHostName + - Location - A property of type System.String, derived from the + directory attribute: location + - ManagedBy - A property of type System.String, derived from the + directory attribute: managedBy + - OperatingSystem - A property of type System.String, derived from + the directory attribute: operatingSystem + - OperatingSystemHotfix - A property of type System.String, derived + from the directory attribute: operatingSystemHotfix + - OperatingSystemServicePack - A property of type System.String, + derived from the directory attribute: operatingSystemServicePack + - OperatingSystemVersion - A property of type System.String, + derived from the directory attribute: operatingSystemVersion + - ServiceAccount - A property of type System.String, derived from + the directory attribute: msDS-HostServiceAccount + - ADServiceAccount - Represents a managed service account; that is, + an Active Directory object of type msDS-ManagerdServiceAccount and + is derived from ADAccount. This class is not supported by AD LDS. + An ADServiceAccount may contain the following properties in + addition to those inherited from its parent. + - HostComputers - A property of type System.String, derived from + the directory attribute: msDS-HostServiceAccountBL + - ADUser - Represents a user (or iNetOrgPerson) and is derived from + ADAccount. An ADUser may contain the following properties in + addition to those inherited from its parent. + - City - A property of type System.String, derived from the + directory attribute: l + - Company - A property of type System.String, derived from the + directory attribute: company + - Country - A property of type System.String, derived from the + directory attribute: c + - Department - A property of type System.String, derived from the + directory attribute: department + - Division - A property of type System.String, derived from the + directory attribute: division + - EmailAddress - A property of type System.String, derived from the + directory attribute: mail + - EmployeeID - A property of type System.String, derived from the + directory attribute: employeeID + - EmployeeNumber - A property of type System.String, derived from + the directory attribute: employeeNumber + - Fax - A property of type System.String, derived from the + directory attribute: facsimileTelephoneNumber + - GivenName - A property of type System.String, derived from the + directory attribute: givenName + - HomeDirectory - A property of type System.String, derived from + the directory attribute: homeDirectory. This property is not + supported by AD LDS. + - HomeDrive - A property of type System.String, derived from the + directory attribute: homeDrive. This property is not supported by + AD LDS. + - HomePhone - A property of type System.String, derived from the + directory attribute: homePhone + - Initials - A property of type System.String, derived from the + directory attribute: initials + - LogonWorkstations - A property of type System.String, derived + from the directory attribute: userWorkstations. This property is + not supported by AD LDS. + - Manager - A property of type System.String, derived from the + directory attribute: manager + - MobilePhone - A property of type System.String, derived from the + directory attribute: mobile + - Office - A property of type System.String, derived from the + directory attribute: physicalDeliveryOfficeName + - OfficePhone - A property of type System.String, derived from the + directory attribute: telephoneNumber + - Organization - A property of type System.String, derived from the + directory attribute: o + - OtherName - A property of type System.String, derived from the + directory attribute: middleName + - POBox - A property of type System.String, derived from the + directory attribute: postOfficeBox + - PostalCode - A property of type System.String, derived from the + directory attribute: postalCode + - ProfilePath - A property of type System.String, derived from the + directory attribute: profilePath. This property is not supported + by AD LDS. + - ScriptPath - A property of type System.String, derived from the + directory attribute: scriptPath. This property is not supported + by AD LDS. + - SmartcardLogonRequired - A property of type System.Boolean, + derived from the directory attributes: userAccountControl, + msDS-User-Account-Control-Computed. This property is not + supported by AD LDS. + - State - A property of type System.String, derived from the + directory attribute: st + - StreetAddress - A property of type System.String, derived from + the directory attribute: streetAddress + - Surname - A property of type System.String, derived from the + directory attribute: sn + - Title - A property of type System.String, derived from the + directory attribute: title + - ADGroup -Represents a group and is derived from ADPrincipal. An + ADGroup may contain the following properties in addition to those + inherited from its parent. + - GroupCategory - A property of type + Microsoft.ActiveDirectory.Management.ADGroupCategory, derived from + the directory attribute: groupType + - GroupScope - A property of type + Microsoft.ActiveDirectory.Management.ADGroupScope, derived from the + directory attribute: groupType + - ManagedBy - A property of type System.String, derived from the + directory attribute: managedBy + - Members - A property of type System.String, derived from the + directory attribute: member + - ADDefaultDomainPasswordPolicy - Represents the domain-wide password policy + of an Active Directory domain and is derived from ADEntity. This class is + not supported by AD LDS. An ADDefaultDomainPasswordPolicy may contain the + following properties in addition to those inherited from its parent. + - ComplexityEnabled - A property of type System.Boolean, derived from the + directory attribute: pwdProperties + - DistinguishedName - A property of type System.String, derived from the + directory attribute: distinguishedName + - LockoutDuration - A property of type System.TimeSpan, derived from the + directory attribute: lockoutDuration + - LockoutObservationWindow - A property of type System.TimeSpan, derived + from the directory attribute: lockoutObservationWindow + - LockoutThreshold - A property of type System.Int32, derived from the + directory attribute: lockoutThreshold + - MaxPasswordAge - A property of type System.TimeSpan, derived from the + directory attribute: maxPwdAge + - MinPasswordAge - A property of type System.TimeSpan, derived from the + directory attribute: minPwdAge + - MinPasswordLength - A property of type System.Int32, derived from the + directory attribute: minPwdLength + - PasswordHistoryCount - A property of type System.Int32, derived from the + directory attribute: pwdHistoryLength + - ReversibleEncryptionEnabled - A property of type System.Boolean, derived + from the directory attribute: pwdProperties + - ADForest - Represents a Active Directory forest in AD DS or a Configuration + Set in AD LDS and is derived from ADEntity. This class is not supported by + AD LDS. An ADForest may contain the following properties in addition to + those inherited from its parent. + - ApplicationPartitions - A property of type System.String, derived from + the directory attribute: ApplicationPartitions + - CrossForestReferences - A property of type System.String, derived from + the directory attribute: CrossForestReferences + - DomainNamingMaster - A property of type System.String, derived from the + directory attribute: DomainNamingMaster + - Domains - A property of type System.String, derived from the directory + attribute: Domains + - ForestMode - A property of type System.Int32, derived from the directory + attribute: msDS-Behavior-Version + - GlobalCatalogs - A property of type System.String, derived from the + directory attribute: GlobalCatalogs + - Name - A property of type System.String, derived from the directory + attribute: name + - PartitionContainerName - A property of type System.String, derived from + the directory attribute: distinguishedName + - RootDomain - A property of type System.String, derived from the directory + attribute: RootDomain + - SchemaMaster - A property of type System.String, derived from the + directory attribute: SchemaMaster + - Sites - A property of type System.String, derived from the directory + attribute: Sites + - SPNSuffixes - A property of type System.String, derived from the + directory attribute: msDS-SPNSuffixes + - UPNSuffixes - A property of type System.String, derived from the + directory attribute: uPNSuffixes + - ADDirectoryServer - Represents a directory server used as either a domain + controller or an AD LDS instance and is derived from ADEntity. An + ADDirectoryServer may contain the following properties in addition to those + inherited from its parent. + - DefaultPartition - A property of type System.String, derived from the + directory attribute: DefaultPartition + - HostName - A property of type System.String, derived from the directory + attribute: HostName + - InvocationId - A property of type System.Guid, derived from the directory + attribute: InvocationId + - IPv4Address - A property of type System.String, derived from the + directory attribute: HostName + - IPv6Address - A property of type System.String, derived from the + directory attribute: HostName + - LdapPort - A property of type System.Int32, derived from the directory + attribute: LdapPort + - Name - A property of type System.String, derived from the directory + attribute: Name + - NTDSSettingsObjectDN - A property of type System.String, derived from the + directory attribute: NTDSSettingsObjectDN + - OperationMasterRoles - A property of type + Microsoft.ActiveDirectory.Management.ADOperationMasterRole, derived from + the directory attribute: OperationMasterRole + - Partitions - A property of type System.String, derived from the directory + attribute: Partitions + - ServerObjectDN - A property of type System.String, derived from the + directory attribute: ServerObjectDN + - ServerObjectGuid - A property of type System.Guid, derived from the + directory attribute: ServerObjectGuid + - Site - A property of type System.String, derived from the directory + attribute: Site + - SslPort - A property of type System.Int32, derived from the directory + attribute: SslPort + - ADDomainController - Represents a domain controller in AD DS and is + derived from ADDirectoryServer. An ADDomainController may contain the + following properties in addition to those inherited from its parent. + - ComputerObjectDN - A property of type System.String, derived from the + directory attribute: ComputerDN + - Domain - A property of type System.String, derived from the directory + attribute: Domain + - Enabled - A property of type System.Boolean, derived from the directory + attribute: Enabled + - Forest - A property of type System.String, derived from the directory + attribute: Forest + - IsGlobalCatalog - A property of type System.Boolean, derived from the + directory attribute: IsGlobalCatalog + - IsReadOnly - A property of type System.Boolean, derived from the + directory attribute: IsReadOnly + - OperatingSystem - A property of type System.String, derived from the + directory attribute: OSName + - OperatingSystemHotfix - A property of type System.String, derived from + the directory attribute: OSHotFix + - OperatingSystemServicePack - A property of type System.String, derived + from the directory attribute: OSServicepack + - OperatingSystemVersion - A property of type System.String, derived from + the directory attribute: OSVersion diff --git a/docset/winserver2012-ps/hyper-v/Get-VMNetworkAdapter.md b/docset/winserver2012-ps/hyper-v/Get-VMNetworkAdapter.md index 60498ae978..4e144f39b5 100644 --- a/docset/winserver2012-ps/hyper-v/Get-VMNetworkAdapter.md +++ b/docset/winserver2012-ps/hyper-v/Get-VMNetworkAdapter.md @@ -132,7 +132,7 @@ Accept wildcard characters: False ### -VM Specifies the virtual machine whose virtual network adapters are to be retrieved. -. The asterisk, "*", is the wildcard. +The asterisk, "*", is the wildcard. If it is specified the cmdlet returns virtual network adapters from every virtual machine in the system. ```yaml diff --git a/docset/winserver2012r2-ps/activedirectory/About/About.md b/docset/winserver2012r2-ps/activedirectory/About/About.md new file mode 100644 index 0000000000..449df28850 --- /dev/null +++ b/docset/winserver2012r2-ps/activedirectory/About/About.md @@ -0,0 +1,26 @@ +--- +description: About articles for the ActiveDirectory module. +Help Version: 3.1.0.0 +Locale: en-US +ms.date: 07/03/2024 +title: About articles +--- +# About topics + +## Description + +About topics cover a range of concepts about PowerShell. + +## About Topics + +### [about_ActiveDirectory](about_ActiveDirectory.md) +The Active Directory module is a command line interface for managing Active Directory. + +### [about_ActiveDirectory_Filter](about_ActiveDirectory_Filter.md) +Describes the syntax and behavior of the search filter supported by the Active Directory module for Windows PowerShell. + +### [about_ActiveDirectory_Identity](about_ActiveDirectory_Identity.md) +The Active Directory module for Windows PowerShell objects have a range of identifying attributes that are used for search and retrieval. + +### [about_ActiveDirectory_ObjectModel](about_ActiveDirectory_ObjectModel.md) +Describes the object model of the Active Directory module for Windows PowerShell. diff --git a/docset/winserver2012r2-ps/activedirectory/About/about_ActiveDirectory.md b/docset/winserver2012r2-ps/activedirectory/About/about_ActiveDirectory.md new file mode 100644 index 0000000000..1b7183dcd2 --- /dev/null +++ b/docset/winserver2012r2-ps/activedirectory/About/about_ActiveDirectory.md @@ -0,0 +1,81 @@ +--- +title: about_ActiveDirectory +ms.date: 04/22/2013 +description: The Active Directory module is a command line interface for managing Active Directory. +Locale: en-US +schema: 2.0.0 +--- + +# about_ActiveDirectory + +## SHORT DESCRIPTION + +The Active Directory module is a command line interface for managing Active +Directory. + +## LONG DESCRIPTION + +The Active Directory module for Windows PowerShell is for IT Professionals who +are administering and interfacing with Active Directory. The Active Directory +module provides an efficient way to complete many administrative, +configuration, and diagnostic tasks across Active Directory Domain Services (AD +DS) and Active Directory Lightweight Directory Services (AD LDS) instances in +their environments. The Active Directory module includes a set of Windows +PowerShell cmdlets and a provider. The provider exposes the Active Directory +database through a hierarchical navigation system, which is very similar to the +file system. As with drives in a file system, such as C:, you can connect +Windows PowerShell drives to Active Directory domains and AD LDS, as well as +Active Directory snapshots. + +### Coverage of Active Directory Module Cmdlets + +Create, Read, Update, and Delete actions are supported for Active Directory +objects by cmdlets such as `New-ADUser`, `Get-ADOrganizationalUnit`, +`Set-ADComputer`, and `Remove-ADUser`. + +Account and Password Policy Management are supported by cmdlets such as +`Enable-ADAccount`, `Unlock-ADAccount`, `New-ADServiceAccount`, +`Set-ADAccountControl`, and `Remove-ADFineGrainedPasswordPolicy`. + +Domain and Forest Management is supported by cmdlets such as `Get-ADForest`, +`Set-ADForest`, `Set-ADForestMode`, `Enable-ADOptionalFeature`, +`Get-ADDomainController`, and `Get-ADDomain`. + +### Listing the Active Directory Module Cmdlets + +To get a list of all of the Active Directory module cmdlets, run + +```powershell +Get-Command -Module ActiveDirectory +``` + +### Getting Started + +Getting started with the Active Directory module for Windows PowerShell is as +easy as clicking the following shortcut: + +Run the following command in any Windows PowerShell prompt to import the Active +Directory module: + +```powershell +Import-Module ActiveDirectory +``` + +### Overview and Conceptual Topics + +The first two of these topics offer a high level overview of the Active +Directory module and the Active Directory Provider. + +- For a brief introduction to the Active Directory provider for Windows + PowerShell, see [ActiveDirectory](/powershell/module/activedirectory). +- The following topics are conceptual support topics for the Active Directory + module cmdlets. + - For an introduction to the **Identity** parameter, which is used by the + Active Directory module cmdlets to identify objects in the directory, see + [about_ActiveDirectory_Identity](about_ActiveDirectory_Identity.md). + - For an introduction to the **Filter** parameter which is used by Active + Directory module cmdlets to search for objects in the directory, see + [about_ActiveDirectory_Filter](about_ActiveDirectory_Filter.md). + - For an introduction to the .NET Framework-based object model implemented by + the Active Directory module, see + [about_ActiveDirectory_ObjectModel](about_ActiveDirectory_ObjectModel.md). diff --git a/docset/winserver2012r2-ps/activedirectory/About/about_ActiveDirectory_Filter.md b/docset/winserver2012r2-ps/activedirectory/About/about_ActiveDirectory_Filter.md new file mode 100644 index 0000000000..23a83c0a0a --- /dev/null +++ b/docset/winserver2012r2-ps/activedirectory/About/about_ActiveDirectory_Filter.md @@ -0,0 +1,351 @@ +--- +title: about_ActiveDirectory_Filter +ms.date: 04/22/2013 +description: Describes the syntax and behavior of the search filter supported by the Active Directory module for Windows PowerShell. +Locale: en-US +schema: 2.0.0 +--- + +# about_ActiveDirectory_Filter + +## SHORT DESCRIPTION + +Describes the syntax and behavior of the search filter supported by the Active +Directory module for Windows PowerShell. + +## LONG DESCRIPTION + +Most get-AD* Active Directory module cmdlets use the Filter parameter to search +for objects. The Filter parameter has been implemented to replace the function +of the LDAP Filter and adds support for PowerShell variables, rich data types, +improved error checking and an Active Directory extended form of the PowerShell +Expression Language. + + +- Support for LDAP Filter Syntax + + The LDAP filter syntax is supported through the **LDAPFilter** parameter. You + will find LDAP filter examples along with the new Active Directory module + filter examples in the Filter Examples section of this topic. + + +- Search Breadth and Depth + + The breadth and depth of your filter-driven search can be modified by two + Active Directory module cmdlet parameters: **SearchBase** and **SearchScope**. + + When within the context of the Active Directory provider, if the + **Searchbase** parameter is not specified, **SearchBase** will default to the + current path. When not running under the Active Directory provider, the + **SearchBase** will default to the server's **DefaultNamingContext**. + + The **SearchScope** parameter defaults to the value `Subtree`, of the + enumerated type **ADSearchScope**. + + For more information, see the **SearchBase** and **SearchScope** parameter + descriptions on any `Get-AD*` cmdlet. + +- Search Result Behavior + + The behavior of the Active Directory module when returning results of a + search is modified by two cmdlet parameters: **ResultPageSize** and + **ResultSetSize**. + + **ResultSetSize** controls the maximum number of returned objects. + + **ResultPageSize** specifies the maximum number of objects for each returned + page of information. + + See the **ResultPageSize** and **ResultSetSize** parameter descriptions on + any `Get-AD*` cmdlet for more information. + + +- Timeout Behavior + + The following statements specify timeout conditions within the Active + Directory module and describe what can be done about a timeout them. + + The default Active Directory module timeout for all operations is 2 + minutes. + + For search operation, the Active Directory module uses paging control + with a 2-minute timeout for each page search. + + > [!NOTE] + > Because a search may involve multiple server page requests the overall + > search time may exceed 2 minutes. + + A **TimeoutException** error indicates that a timeout has occurred. + + For a search operation, you can choose to use a smaller page size, set with + the **ResultPageSize** parameter, if you are getting a **TimeoutException** + error. + + If after trying these changes you are still getting a **TimeoutException** + error, consider optimizing your filter using the guidance in the + Optimizing Filters section of this topic. + + +- Optimizing Filters + + You can enhance the search filter behavior by using these guidelines. + + - Avoid using the **Recursive** parameter as it intensifies resource usage of + the search operation. + - Avoid using bitwise AND operators and bitwise OR operators. For more + information, see the Supported Operators section of this topic. + - Avoid using the logical NOT operator. + - Break down your search into multiple queries with narrower conditions. + + For a full description of filter syntax and usage, see the Filter Syntax + section of this topic. + + +## Filter Examples + +The following section shows many examples of filter use in common queries. + +### Example 1 - Get all entries: + +- LDAP Filter Equivalent: `(objectClass=*)` + +```powershell +Get-ADObject -Filter 'ObjectClass -like "*"' +``` + +### Example 2 - Get entries containing "bob" somewhere in the common name + +- LDAP Filter Equivalent: `(cn=*bob*)` + +```powershell +Get-ADObject -Filter 'CN -like "*bob*"' +``` + +### Example 3 - Get entries with a bad password count greater than five + +- LDAP Filter Equivalent: `(&(!badpwdcount<=5)(badpwdcount=*))` + +```powershell +Get-ADUser -Filter 'badpwdcount -ge 5' +``` + +### Example 4 - Get all users with an e-mail attribute + +- LDAP Filter Equivalent: `(&(objectClass=user)(email=*))` + +```powershell +Get-ADUser -filter 'email -like "*"' +``` + +-or- + +```powershell +Get-ADObject -filter 'email -like "*" -and ObjectClass -eq "user"' +``` + +### Example 5 - Get all user entries with an e-mail attribute and a surname equal to "smith": + +- LDAP Filter Equivalent: `(&(sn=smith)(objectClass=user)(email=*))` + +```powershell +Get-ADUser -Filter 'Email -like "*" -and SurName -eq "smith"' +``` + +-or- + +```powershell +Get-ADUser -Filter 'Email -like "*" -and sn -eq "smith"' +``` + + +### Example 6 - Get all user entries with a common name that starts with "andy" and users with a common name of "steve" or "margaret" + +- LDAP Filter Equivalent: `(&(objectClass=user) | (cn=andy*)(cn=steve)(cn=margaret))` + +```powershell +Get-ADUser -Filter 'CN -like "andy*" -or CN -eq "steve" -or CN -eq "margaret"' +``` + + +This example demonstrates a more complex logic and the use of precedence +control via parenthesis. + +```powershell +Get-ADObject -Filter 'objectClass -eq "user" -and (CN -like "andy*" -or CN -eq "steve" -or CN -eq "margaret")' +``` + +### Example 7 - Get all entries without an e-mail attribute + +- LDAP Filter Equivalent: `(!(email=*))` + +```powershell +Get-ADUser -Filter '-not Email -like "*"' +``` + +-or- + +```powershell +Get-ADUser -Filter 'Email -notlike "*"' +``` + +### Example 8 - Get all users who did not logon since January 1, 2007 + +- LDAP Filter Equivalent: `(&(lastlogon<=X)(objectClass=user))` where X is + number of 100-nanosecond slices since Jan 1st 1601 + +```powershell +$date = new-object System.DateTime -ArgumentList @(2007,1,1,0,0,0) +Get-ADUser -Filter '-not LastLogon -le $date' +``` + +### Example 9 - Get all users who have logged on in the last 5 days + +- LDAP Filter Equivalent: + + ``` + (&(lastLogon>=128812906535515110) + (objectClass=user)(!(objectClass=computer))) + ``` + +```powershell +$date = (get-date) - (new-timespan -days 5) +Get-ADUser -Filter 'lastLogon -gt $date' +``` + +### Example 10 - Search for group objects that have the ADS_GROUP_TYPE_SECURITY_ENABLED flag set + +- LDAP Filter Equivalent: + `(&(objectCategory=group)(groupType:1.2.840.113556.1.4.803:=2147483648))` + +The following example query string searches for group objects that have the +ADS_GROUP_TYPE_SECURITY_ENABLED flag set. Be aware that the decimal value of +ADS_GROUP_TYPE_SECURITY_ENABLED (0x80000000 = 2147483648) is used for the +comparison value. + +```powershell +Get-ADGroup -filter 'groupType -band 0x80000000' +``` + +### Example 11 - Search the ancestry of an object + +- LDAP Filter Equivalent: + `(memberof:1.2.840.113556.1.4.1941:=(cn=Group1,OU=groupsOU,DC=x)))` + +The LDAP_MATCHING_RULE_IN_CHAIN is a matching rule OID that is designed to +provide a method to look up the ancestry of an object. Many applications using +Active Directory and AD LDS usually work with hierarchical data, which is +ordered by parent-child relationships. Previously, applications performed +transitive group expansion to figure out group membership, which used a lot of +network bandwidth. Applications made multiple round-trips to figure out if an +object fell "in the chain" if a link were traversed through to the end. + +An example of such a query is one designed to check if a user, "user1" is a +member of group "group1". "user1" may not be a direct member of group1. It +could be a member of some other group, which is a member of "group1". + +You would set the base to the user DN and the scope to base, and use the query: + +```powershell +Get-ADUser -Filter 'memberOf -RecursiveMatch "CN=Administrators, CN=Builtin,DC=Fabrikam,DC=com"' -SearchBase "CN=Administrator,CN=Users,DC=Fabrikam,DC=com" +``` + +## Filter Syntax + +The following syntax descriptions use Backus-Naur form to show the PowerShell +Expression Language for the Filter parameter. + +```Syntax + ::= "{" "}" + + ::= | + | + + + ::= | + "(" ")" + + ::= "-eq" | "-le" | "-ge" | "-ne" | "-lt" | "-gt" | + "-approx" | "-bor" | "-band" | "-recursivematch" | "-like" | + "-notlike" + + ::= "-and" | "-or" + + ::= "-not" + + ::= | + +::= < this value will be compared to the object data for + attribute using the specified filter operator +``` + + +## Supported Operators + +The following table shows frequently used search filter operators. + +| Operator | Description | LDAP Equivalent | +| ----------------- | -------------------------------------- | -------------------------- | +| `-eq` | Equal to. Wildcards not supported. | = | +| `-ne` | Not equal to. Wildcards not supported. | !x = y | +| `-approx` | Approximately equal to | ~= | +| `-le` | Lexicographically less than | <= | +| | or equal to | | +| `-lt` | Lexicographically less than | !x >= y | +| `-ge` | Lexicographically greater | >= | +| | than or equal to | | +| `-gt` | Lexicographically greater than | !x <= y | +| | | | +| `-and` | AND | & | +| `-or` | OR | | +| `-not` | NOT | ! | +| `-bor` | Bitwise OR | :1.2.840.113556.1.4.804:= | +| `-band` | Bitwise AND | :1.2.840.113556.1.4.803:= | +| `-recursivematch` | Use LDAP_MATCHING_RULE_IN_CHAIN | :1.2.840.113556.1.4.1941:= | +| `-like` | Similar to `-eq` and supports | = | +| | wildcard comparison. The only | | +| | wildcard character supported is: `*` | | +| `-notlike` | Not like. Supports wild | !x = y | +| | card comparison. | | + +> [!NOTE] +> PowerShell wildcards, other than "*", such as "?" are not supported by the +> **Filter** parameter syntax. + +### Operator Precedence + +The following listing shows the precedence of operators for filters from +highest to lowest. + +- Highest precedence: `-eq`, `-ge`, `-le`, `-approx`, `-band`, `-bor`, + `-recursivematch`, `-ne`, `-like`, `-not`, `-and` +- Lowest precedence: `-or` + +### Special Characters + +The following escape sequence should be used for specifying special characters +in AD Filter STRING data, that is, data enclosed in double or single quotes. + +| ASCII Character | Escape sequence substitute | +| --------------- | --------------------------------------------------- | +| `"` | `` `" `` (This escape sequence is only required if | +| | STRING data is enclosed in double quotes.) | +| `'` | `''` (This escape sequence is only required if | +| | STRING data is enclosed in single quotes.) | +| NUL | `\00` (This is a standard LDAP escape sequence.) | +| `\` | `\5c` (This is a standard LDAP escape sequence.) | + +### LDAP Special Characters + +ADFilter parser will automatically convert all the below characters found in +STRING data, that is data enclosed in " " or ' ' to their LDAP escape sequence. +End users need not know about these LDAP escape sequence. + +| ASCII Character | Escape sequence substitute | +| --------------- | ----------------------------------------------- | +| `*` | `\2a` (Character `*` will only be converted in | +| | -eq and -ne comparisons Users should use | +| | -like and -notlike operators for wildcard | +| | comparison.) | +| `(` | `\28` | +| `)` | `\29` | +| `/` | `\2f` | diff --git a/docset/winserver2012r2-ps/activedirectory/About/about_ActiveDirectory_Identity.md b/docset/winserver2012r2-ps/activedirectory/About/about_ActiveDirectory_Identity.md new file mode 100644 index 0000000000..c007277b19 --- /dev/null +++ b/docset/winserver2012r2-ps/activedirectory/About/about_ActiveDirectory_Identity.md @@ -0,0 +1,196 @@ +--- +title: about_ActiveDirectory_Identity +ms.date: 04/22/2013 +description: This article lists the identifying attributes that are used for search and retrieval supported by the Active Directory module for Windows PowerShell. +Locale: en-US +schema: 2.0.0 +--- + +# about_ActiveDirectory_Identity + +## SHORT DESCRIPTION + +The Active Directory module for Windows PowerShell objects have a range of +identifying attributes that are used for search and retrieval. + +## LONG DESCRIPTION + +In order to identify the objects in Active Directory, each object has +attributes that can be used as identifiers. In the Active Directory module, the +value of the identity of an object can be passed using the Identity parameter. +Each object type has its own set of possible types and values for use by the +Identity parameter. See the detailed description of the Identity parameter of +the given cmdlet for more information about its usage. + +When searching with the Active Directory module cmdlets, the value of the +Identity parameter, along with the values of the Server and Partition +parameters, is used to uniquely identify a single object. The Server parameter +is used to locate which server to connect with. The Partition parameter further +narrows the search to a specific partition. The Identity parameter then +resolves to a single unique object in the partition. + +Note that using the Security Accounts Manager (SAM) Account Name +(**sAMAccountName**) when targeting a global catalog port, you will not find a +user in a different domain if you are using the Identity parameter + +If more than one object is found using identity resolution, the Active +Directory module throws an error. + +For more information about the Server and Partition parameters, see the help +topics for the individual cmdlets where they are used, such as `Get-ADUser`, by +typing: + +```powershell +Get-Help Get-ADUser +``` + +### Objects and Identities + +Each object has a list of attributes that can be used as an identity for that +object. Additionally, if the object inherits from another object, then the +parent object's identities can also be used as the child object's identities. +For more information on the Active Directory object hierarchy, see +[about_ActiveDirectory_ObjectModel](about_ActiveDirectory_ObjectModel.md). + +> [!NOTE] +> For Active Directory Provider cmdlets, only an object's 'Distinguished Name' +> or 'Relative Distinguished Name' can be used as the identity. For a list of +> Active Directory Provider cmdlets, see ActiveDirectory. + +### Identity Attributes + +The following is a list of identity attributes by object type. + +- ADAccount + - Distinguished Name + - GUID (objectGUID) + - Security Identifier (objectSid) + - SAM Account Name (sAMAccountName) + +- ADComputer + - Distinguished Name + - GUID (objectGUID) + - Security Identifier (objectSid) + - Security Accounts Manager Account Name (sAMAccountName) + +- ADDirectoryServer + - Name of the server object (name) + - For AD LDS instances the syntax of a name is `$` + - For other Active Directory instances, use the value of the name property. + - Distinguished Name of the NTDS Settings object + - Distinguished Name of the server object that represents the directory + server. + - GUID (objectGUID) of server object under the configuration partition. + - GUID (objectGUID) of NTDS settings object under the configuration partition + +- ADDomain + - Distinguished Name + - GUID + - Security Identifier + - DNS domain name + - NetBIOS domain name + +- ADDomainController + - GUID (objectGUID) + - IPV4Address + - Global IPV6Address + - DNS Host Name (dNSHostName) + - Name of the server object + - Distinguished Name of the NTDS Settings object + - Distinguished Name of the server object that represents the domain controller + - GUID of NTDS settings object under the configuration partition + - GUID of server object under the configuration partition + - Distinguished Name of the computer object that represents the domain controller. + +- ADFineGrainedPasswordPolicy + - Distinguished Name + - GUID (objectGUID) + - Name (name) + +- ADForest + - Fully qualified domain name + - DNS host name + - NetBIOS name + +- ADGroup + - Distinguished Name + - GUID (objectGUID) + - Security Identifier (objectSid) + - Security Accounts Manager (SAM) Account Name (sAMAccountName) + +- ADObject + - Distinguished Name + - GUID (objectGUID) + +- ADOptionalFeature + - Distinguished Name + - Name (name) + - Feature GUID (featureGUID) + - GUID (objectGUID) + +- ADOrganizationalUnit + - Distinguished Name + - GUID (objectGUID) + +- ADPrincipal + - Distinguished Name + - GUID (objectGUID) + - Security Identifier (objectSid) + - SAM Account Name (sAMAccountName) + +- ADServiceAccount + - Distinguished Name + - GUID (objectGUID) + - Security Identifier (objectSid) + - SAM Account Name (sAMAccountName) + +- ADUser + - Distinguished Name + - GUID (objectGUID) + - Security Identifier (objectSid) + - SAM User Name (sAMUserName) + + +### Identities Formats + +Active Directory module objects have a range of identity attributes. Below is a +list of these, their types and formats. + +- Distinguished Name + - Example: CN=SaraDavis,CN=Europe,CN=Users, DC=corp,DC=contoso,DC=com + +- DNS domain name + - Example: redmond.corp.contoso.com + +- DNS Host Name (dNSHostName) + - Example: corp-DC01.corp.contoso.com + +- Feature GUID (featureGUID) + - Example: 599c3d2e-f72d-4d20-8a88-030d99495f20 + +- Fully qualified domain name + - Example: corp.contoso.com + +- Global IPV6Address + - Example: 2001:4898:0:fff:200:5efe:157.59.132.61 + +- GUID (objectGUID) + - Example: 599c3d2e-f72d-4d20-8a88-030d99495f20 + +- IPV4Address + - Example:157.59.132.61 + +- NetBIOS domain name + - Example: redmond + +- Name of the server object + - Example: corp-DC01$ + +- SAM Account Name (sAMAccountName) + - Example: saradavisreports + +- Security Identifier (objectSid) + - Example: S-1-5-21-3165297888-301567370-576410423-1103 + +- Name + - Example: Recycle Bin Feature diff --git a/docset/winserver2012r2-ps/activedirectory/About/about_ActiveDirectory_ObjectModel.md b/docset/winserver2012r2-ps/activedirectory/About/about_ActiveDirectory_ObjectModel.md new file mode 100644 index 0000000000..8535a97464 --- /dev/null +++ b/docset/winserver2012r2-ps/activedirectory/About/about_ActiveDirectory_ObjectModel.md @@ -0,0 +1,595 @@ +--- +title: about_ActiveDirectory_ObjectModel +ms.date: 04/22/2013 +description: Describes the object model of the Active Directory module for Windows PowerShell. +Locale: en-US +schema: 2.0.0 +--- + +# about_ActiveDirectory_ObjectModel + +## SHORT DESCRIPTION +Describes the object model of the Active Directory module for Windows +PowerShell. + +## LONG DESCRIPTION + +This topic explains the Active Directory module classes and their properties +used to model actual Active Directory attributes. It also outlines the class +hierarchy constructed from its Active Directory counterpart. The object model +establishes a data foundation for all the operations supported by Active +Directory module cmdlets. + +### Class Hierarchy + +The following list shows the class hierarchy defined in the Active Directory +module object model, with class inheritance implied by indentation. This +inheritance model allows for Active Directory cmdlets to accept a range of +object types as input. This means, for example, that the cmdlet +Get-ADPrincipalGroupMembership can accept as input any of the following +objects: ADGroup, ADAccount, ADComputer, ADServiceAccount or ADUser. This works +because of the inheritance model and guarantees that an ADUser object has all +of the properties of an ADPrincipal object. + +``` +ADEntity + ADRootDSE + ADObject + ADFineGrainedPasswordPolicy + ADOptionalFeature + ADOrganizationalUnit + ADPartition + ADDomain + ADPrincipal + ADAccount + ADComputer + ADServiceAccount + ADUser + ADGroup + ADDefaultDomainPasswordPolicy + ADForest + ADDirectoryServer + ADDomainController +``` + +### Active Directory Module Classes + +The following listing shows every Active Directory module class from the class +hierarchy listing. Each class defines a set of properties, some of which are +LDAP attributes that are retrieved by default and some are new properties +created specifically for the Active Directory module. These new properties are +derived from one or more LDAP attributes as outlined in the class listings. + + +- ADEntity - The base level class from which all other classes are derived. + - ADRootDSE - Represents the rootDSE and is derived from ADEntity. An + ADRootDSE may contain the following properties in addition to those + inherited from its parent. + - ConfigurationNamingContext - A property of type System.String, derived + from the directory attribute ConfigurationNamingContext + - CurrentTime - A property of type System.DateTime, derived from the + directory attribute CurrentTime + - DefaultNamingContext - A property of type System.String, derived from the + directory attribute DefaultNamingContext + - DnsHostName - A property of type System.String, derived from the + directory attribute DnsHostName + - DomainControllerFunctionality - A property of type + ADDomainControllerMode, derived from the directory attribute + DomainControllerFunctionality + - DomainFunctionality - A property of type ADDomainMode, derived from the + directory attribute DomainFunctionality + - DsServiceName - A property of type System.String, derived from the + directory attribute DsServiceName + - ForestFunctionality - A property of type ADForestMode, derived from the + directory attribute ForestFunctionality + - GlobalCatalogReady - A property of type System.Boolean, derived from the + directory attribute GlobalCatalogReady + - HighestCommittedUSN - A property of type System.Long, derived from the + directory attribute HighestCommittedUSN + - LdapServiceName - A property of type System.String, derived from the + directory attribute LdapServiceName + - NamingContexts - A property of type System.String, derived from the + directory attribute NamingContexts + - RootDomainNamingContext - A property of type System.String, derived from + the directory attribute RootDomainNamingContext + - SchemaNamingContext - A property of type System.String, derived from the + directory attribute SchemaNamingContext + - ServerName - A property of type System.String, derived from the directory + attribute ServerName + - SubschemaSubentry - A property of type ADObject, derived from the + directory attribute SubschemaSubentry + - SupportedCapabilities - A property of type ADObjectIdentifier, derived + from the directory attribute SupportedCapabilities + - SupportedControl - A property of type ADObjectIdentifier, derived from + the directory attribute SupportedControl + - SupportedLDAPPolicies - A property of type System.String, derived from + the directory attribute SupportedLDAPPolicies + - SupportedLDAPVersion - A property of type System.Int, derived from the + directory attribute SupportedLDAPVersion + - SupportedRootDSEOperations - A property of type + ADPropertyValueCollection, derived from the directory attribute + SupportedRootDSEOperations + - SupportedSASLMechanisms - A property of type System.String, derived from + the directory attribute SupportedSASLMechanisms + - Syncronized - A property of type System.Boolean, derived from the + directory attribute IsSynchronized. + - ADObject - Represents any object in Active Directory and is derived from + ADEntity. An ADObject may contain the following properties in addition to + those inherited from its parent. + - CanonicalName - A property of type System.String, derived from the + directory attribute: canonicalName + - CN - A property of type System.String, derived from the directory + attribute: cn + - Created - A property of type System.DateTime, derived from the directory + attribute: createTimeStamp + - Deleted - A property of type System.Boolean, derived from the directory + attribute: isDeleted + - Description - A property of type System.String, derived from the + directory attribute: description + - DisplayName - A property of type System.String, derived from the + directory attribute: displayName + - DistinguishedName - A property of type System.String, derived from the + directory attribute: distinguishedName + - LastKnownParent - A property of type System.String, derived from the + directory attribute: lastKnownParent + - Modified - A property of type System.DateTime, derived from the directory + attribute: modifyTimeStamp + - Name - A property of type System.String, derived from the directory + attribute: name + - ObjectCategory - A property of type System.String, derived from the + directory attribute: objectCategory + - ObjectClass - A property of type System.String, derived from the + directory attribute: objectClass + - ObjectGUID - A property of type System.Guid, derived from the directory + attribute: objectGUID + - ProtectedFromAccidentalDeletion - A property of type System.Boolean, + derived from the directory attributes: nTSecurityDescriptor, + sdRightsEffective, instanceType, isDeleted + - ADFineGrainedPasswordPolicy Represents a fine grained password policy + object; that is, an AD object of type msDS-PasswordSettings in AD DS and + is derived from ADObject. This class is not supported by AD LDS. An + ADFineGrainedPasswordPolicy may contain the following properties in + addition to those inherited from its parent. + - AppliesTo - A property of type System.String, derived from the + directory attribute: msDS-PSOAppliesTo + - ComplexityEnabled - A property of type System.Boolean, derived from the + directory attribute: msDS-PasswordComplexityEnabled + - LockoutDuration - A property of type System.TimeSpan, derived from the + directory attribute: msDS-LockoutDuration + - LockoutObservationWindow - A property of type System.TimeSpan, derived + from the directory attribute: msDS-LockoutObservationWindow + - LockoutThreshold - A property of type System.Int32, derived from the + directory attribute: msDS-LockoutThreshold + - MaxPasswordAge - A property of type System.TimeSpan, derived from the + directory attribute: msDS-MaximumPasswordAge + - MinPasswordAge - A property of type System.TimeSpan, derived from the + directory attribute: msDS-MinimumPasswordAge + - MinPasswordLength - A property of type System.Int32, derived from the + directory attribute: msDS-MinimumPasswordLength + - PasswordHistoryCount - A property of type System.Int32, derived from + the directory attribute: msDS-PasswordHistoryLength + - Precedence - A property of type System.Int32, derived from the + directory attribute: msDS-PasswordSettingsPrecedence + - ReversibleEncryptionEnabled - A property of type System.Boolean, + derived from the directory attribute: + msDS-PasswordReversibleEncryptionEnabled + - ADOptionalFeature Represents an optional feature, an Active Directory + object of type msDS-OptionalFeature, and is derived from ADObject. An + ADOptionalFeaturemay contain the following properties in addition to + those inherited from its parent. + - EnabledScopes - A property of type System.String, derived from the + directory attribute: msDS-EnabledFeatureBL + - FeatureGUID - A property of type System.Guid, derived from the + directory attribute: msDS-OptionalFeatureGUID + - FeatureScope - A property of type System.Int32, derived from the + directory attribute: msDS-OptionalFeatureFlags + - IsDisableable - A property of type System.Boolean, derived from the + directory attribute: msDS-OptionalFeatureFlags + - RequiredDomainMode - A property of type + Microsoft.ActiveDirectory.Management.ADDomainMode, derived from the + directory attribute: msDS-RequiredDomainBehaviorVersion + - RequiredForestMode - A property of type + Microsoft.ActiveDirectory.Management.ADForestMode, derived from the + directory attribute: msDS-RequiredForestBehaviorVersion + - ADOrganizationalUnit Represents an organizationalUnit (OU) object and is + derived from ADObject. An ADOrganizationalUnit may contain the following + properties in addition to those inherited from its parent. + - City - A property of type System.String, derived from the directory + attribute: l + - Country - A property of type System.String, derived from the directory + attribute: c + - LinkedGroupPolicyObjects - A property of type System.String, derived + from the directory attribute: gpLink. This property is not supported on + AD LDS. + - ManagedBy - A property of type System.String, derived from the + directory attribute: managedBy + - PostalCode - A property of type System.String, derived from the + directory attribute: postalCode + - State - A property of type System.String, derived from the directory + attribute: st + - StreetAddress - A property of type System.String, derived from the + directory attribute: street + - ADPartition - Represents a naming context, Configuration, Schema, Domain + or Application Partition(ND NC) and is derived from ADObject. This class + is not supported by AD LDS. An ADPartition may contain the following + properties in addition to those inherited from its parent. + - DeletedObjectsContainer - A property of type System.String, derived + from the directory attribute: DeletedObjectsContainer + - DNSRoot - A property of type System.String, derived from the directory + attribute: DNSRoot + - LostAndFoundContainer - A property of type System.String, derived from + the directory attribute: LostAndFoundContainer + - QuotasContainer - A property of type System.String, derived from the + directory attribute: QuotasContainer + - ReadOnlyReplicaDirectoryServers - A property of type System.String, + derived from the directory attribute: ReadOnlyReplicaDirectoryServers + - ReplicaDirectoryServers - A property of type System.String, derived + from the directory attribute: ReplicaDirectoryServers + - SubordinateReferences - A property of type System.String, derived from + the directory attribute: SubordinateReferences + - ADDomain - Represents a domain in AD DS or an instance in AD LDS; for + example, an Active Directory object of type domainDNS and is derived + from ADPartition. This class is not supported by AD LDS. An ADDomain + may contain the following properties in addition to those inherited + from its parent. + - AllowedDNSSuffixes - A property of type System.String, derived from + the directory attribute: msDS-AllowedDNSSuffixes + - ChildDomains - A property of type System.String, derived from the + directory attribute: ChildDomains + - ComputersContainer - A property of type System.String, derived from + the directory attribute: ComputersContainer + - DomainControllersContainer - A property of type System.String, + derived from the directory attribute: DomainControllersContainer + - DomainMode - A property of type System.Int32, derived from the + directory attribute: msDS-Behavior-Version + - DomainSID - A property of type + System.Security.Principal.SecurityIdentifier, derived from the + directory attribute: objectSid + - ForeignSecurityPrincipalsContainer - A property of type + System.String, derived from the directory attribute: + ForeignSecurityPrincipalsContainer + - Forest - A property of type System.String, derived from the directory + attribute: Forest + - InfrastructureMaster - A property of type System.String, derived from + the directory attribute: InfrastructureMaster + - LastLogonReplicationInterval - A property of type System.TimeSpan, + derived from the directory attribute: msDS-LogonTimeSyncInterval + - LinkedGroupPolicyObjects - A property of type System.String, derived + from the directory attribute: LinkedGroupPolicyObjects + - ManagedBy - A property of type System.String, derived from the + directory attribute: managedBy + - NetBIOSName - A property of type System.String, derived from the + directory attribute: NetBIOSName + - ParentDomain - A property of type System.String, derived from the + directory attribute: ParentDomain + - PDCEmulator - A property of type System.String, derived from the + directory attribute: PDCEmulator + - RIDMaster - A property of type System.String, derived from the + directory attribute: RIDMaster + - SystemsContainer - A property of type System.String, derived from the + directory attribute: SystemsContainer + - UsersContainer - A property of type System.String, derived from the + directory attribute: UsersContainer + - ADPrincipal - Represents a security principal, which is an Active + Directory object of type user, computer, group or iNetOrgPerson and is + derived from ADObject. An ADPrincipal may contain the following + properties in addition to those inherited from its parent. + - HomePage - A property of type System.String, derived from the + directory attribute: wWWHomePage + - MemberOf - A property of type System.String, derived from the + directory attribute: memberOf + - SamAccountName - A property of type System.String, derived from the + directory attribute: sAMAccountName. This property is not supported + for AD LDS. + - SID - A property of type + System.Security.Principal.SecurityIdentifier, derived from the + directory attribute: objectSid + - SIDHistory - A property of type + System.Security.Principal.SecurityIdentifier, derived from the + directory attribute: sIDHistory. This property is not supported for + AD LDS. + - ADAccount - Represents a security account; that is, an Active + Directory object of type user, computer or iNetOrgPerson and is + derived from ADPrincipal. An ADAccount may contain the following + properties in addition to those inherited from its parent. + - AccountExpirationDate - A property of type System.DateTime, derived + from the directory attribute: accountExpires + - AccountLockoutTime - A property of type System.DateTime, derived + from the directory attribute: lockoutTime + - AccountNotDelegated - A property of type System.Boolean, derived + from the directory attributes: userAccountControl, + msDS-User-Account-Control-Computed. This property is not supported + by AD LDS. + - AllowReversiblePasswordEncryption - A property of type + System.Boolean, for AD DS it is derived from the directory + attribute: userAccountControl; for AD LDS it is derived from the + directory attribute: ms-DS-UserEncryptedTextPasswordAllowed + - BadLogonCount - A property of type System.Int32, derived from the + directory attribute: badPwdCount + - CannotChangePassword - A property of type System.Boolean, derived + from the directory attribute: nTSecurityDescriptor + - Certificates - A property of type + System.Security.Cryptography.X509Certificates.X509Certificate, + derived from the directory attribute: userCertificate + - DoesNotRequirePreAuth - A property of type System.Boolean, derived + from the directory attributes: userAccountControl, + msDS-User-Account-Control-Computed. This property is not supported + by AD LDS. + - Enabled - A property of type System.Boolean, for AD DS it is + derived from the directory attributes: userAccountControl, + msDS-User-Account-Control-Computed; for AD LDS it is derived from + the directory attribute msDS-UserAccountDisabled + - HomedirRequired - A property of type System.Boolean, derived from + the directory attributes: userAccountControl, + msDS-User-Account-Control-Computed. This property is not supported + by AD LDS. + - LastBadPasswordAttempt - A property of type System.DateTime, + derived from the directory attribute: badPasswordTime + - LastLogonDate - A property of type System.DateTime, derived from + the directory attribute: lastLogonTimestamp + - LockedOut - A property of type System.Boolean, for AD DS it is + derived from the directory attributes: userAccountControl, + msDS-User-Account-Control-Computed, lockoutTime; for AD LDS it is + derived from the directory attribute msDS-UserAccountDisabled + - MNSLogonAccount - A property of type System.Boolean, derived from + the directory attributes: userAccountControl, + msDS-User-Account-Control-Computed. This property is not supported + by AD LDS. + - PasswordExpired - A property of type System.Boolean, for AD DS it + is derived from the directory attributes: userAccountControl, + msDS-User-Account-Control-Computed; for AD LDS it is derived from + the directory attribute msDS-UserPasswordExpired + - PasswordLastSet - A property of type System.DateTime, derived from + the directory attribute: pwdLastSet + - PasswordNeverExpires - A property of type System.Boolean, for AD + LDS it is derived from the directory attributes: + userAccountControl, msDS-User-Account-Control-Computed; for AD LDS + it is derived from the directory attribute: + msDS-UserDontExpirePassword + - PasswordNotRequired - A property of type System.Boolean, for AD DS + it is derived from the directory attributes: userAccountControl, + msDS-User-Account-Control-Computed; for AD LDS it is derived from + the directory attribute: ms-DS-UserPasswordNotRequired + - PrimaryGroup - A property of type System.String, derived from the + directory attributes: primaryGroupID, objectSid. This property is + not supported by AD LDS. + - ServicePrincipalNames - A property of type System.String, derived + from the directory attribute: servicePrincipalName. This property + is not supported by AD LDS. + - TrustedForDelegation - A property of type System.Boolean, derived + from the directory attributes: userAccountControl, + msDS-User-Account-Control-Computed. This property is not supported + by AD LDS. + - TrustedToAuthForDelegation - A property of type System.Boolean, + derived from the directory attributes: userAccountControl, + msDS-User-Account-Control-Computed. This property is not supported + by AD LDS. + - UseDESKeyOnly - A property of type System.Boolean, derived from the + directory attributes: userAccountControl, + msDS-User-Account-Control-Computed. This property is not supported + by AD LDS. + - UserPrincipalName - A property of type System.String, derived from + the directory attribute: userPrincipalName + - ADComputer - Represents a computer and is derived from ADAccount. + An ADComputer may contain the following properties in addition to + those inherited from its parent. + - DNSHostName - A property of type System.String, derived from the + directory attribute: dNSHostName + - IPv4Address - A property of type System.String, derived from the + directory attribute: dNSHostName + - IPv6Address - A property of type System.String, derived from the + directory attribute: dNSHostName + - Location - A property of type System.String, derived from the + directory attribute: location + - ManagedBy - A property of type System.String, derived from the + directory attribute: managedBy + - OperatingSystem - A property of type System.String, derived from + the directory attribute: operatingSystem + - OperatingSystemHotfix - A property of type System.String, derived + from the directory attribute: operatingSystemHotfix + - OperatingSystemServicePack - A property of type System.String, + derived from the directory attribute: operatingSystemServicePack + - OperatingSystemVersion - A property of type System.String, + derived from the directory attribute: operatingSystemVersion + - ServiceAccount - A property of type System.String, derived from + the directory attribute: msDS-HostServiceAccount + - ADServiceAccount - Represents a managed service account; that is, + an Active Directory object of type msDS-ManagerdServiceAccount and + is derived from ADAccount. This class is not supported by AD LDS. + An ADServiceAccount may contain the following properties in + addition to those inherited from its parent. + - HostComputers - A property of type System.String, derived from + the directory attribute: msDS-HostServiceAccountBL + - ADUser - Represents a user (or iNetOrgPerson) and is derived from + ADAccount. An ADUser may contain the following properties in + addition to those inherited from its parent. + - City - A property of type System.String, derived from the + directory attribute: l + - Company - A property of type System.String, derived from the + directory attribute: company + - Country - A property of type System.String, derived from the + directory attribute: c + - Department - A property of type System.String, derived from the + directory attribute: department + - Division - A property of type System.String, derived from the + directory attribute: division + - EmailAddress - A property of type System.String, derived from the + directory attribute: mail + - EmployeeID - A property of type System.String, derived from the + directory attribute: employeeID + - EmployeeNumber - A property of type System.String, derived from + the directory attribute: employeeNumber + - Fax - A property of type System.String, derived from the + directory attribute: facsimileTelephoneNumber + - GivenName - A property of type System.String, derived from the + directory attribute: givenName + - HomeDirectory - A property of type System.String, derived from + the directory attribute: homeDirectory. This property is not + supported by AD LDS. + - HomeDrive - A property of type System.String, derived from the + directory attribute: homeDrive. This property is not supported by + AD LDS. + - HomePhone - A property of type System.String, derived from the + directory attribute: homePhone + - Initials - A property of type System.String, derived from the + directory attribute: initials + - LogonWorkstations - A property of type System.String, derived + from the directory attribute: userWorkstations. This property is + not supported by AD LDS. + - Manager - A property of type System.String, derived from the + directory attribute: manager + - MobilePhone - A property of type System.String, derived from the + directory attribute: mobile + - Office - A property of type System.String, derived from the + directory attribute: physicalDeliveryOfficeName + - OfficePhone - A property of type System.String, derived from the + directory attribute: telephoneNumber + - Organization - A property of type System.String, derived from the + directory attribute: o + - OtherName - A property of type System.String, derived from the + directory attribute: middleName + - POBox - A property of type System.String, derived from the + directory attribute: postOfficeBox + - PostalCode - A property of type System.String, derived from the + directory attribute: postalCode + - ProfilePath - A property of type System.String, derived from the + directory attribute: profilePath. This property is not supported + by AD LDS. + - ScriptPath - A property of type System.String, derived from the + directory attribute: scriptPath. This property is not supported + by AD LDS. + - SmartcardLogonRequired - A property of type System.Boolean, + derived from the directory attributes: userAccountControl, + msDS-User-Account-Control-Computed. This property is not + supported by AD LDS. + - State - A property of type System.String, derived from the + directory attribute: st + - StreetAddress - A property of type System.String, derived from + the directory attribute: streetAddress + - Surname - A property of type System.String, derived from the + directory attribute: sn + - Title - A property of type System.String, derived from the + directory attribute: title + - ADGroup -Represents a group and is derived from ADPrincipal. An + ADGroup may contain the following properties in addition to those + inherited from its parent. + - GroupCategory - A property of type + Microsoft.ActiveDirectory.Management.ADGroupCategory, derived from + the directory attribute: groupType + - GroupScope - A property of type + Microsoft.ActiveDirectory.Management.ADGroupScope, derived from the + directory attribute: groupType + - ManagedBy - A property of type System.String, derived from the + directory attribute: managedBy + - Members - A property of type System.String, derived from the + directory attribute: member + - ADDefaultDomainPasswordPolicy - Represents the domain-wide password policy + of an Active Directory domain and is derived from ADEntity. This class is + not supported by AD LDS. An ADDefaultDomainPasswordPolicy may contain the + following properties in addition to those inherited from its parent. + - ComplexityEnabled - A property of type System.Boolean, derived from the + directory attribute: pwdProperties + - DistinguishedName - A property of type System.String, derived from the + directory attribute: distinguishedName + - LockoutDuration - A property of type System.TimeSpan, derived from the + directory attribute: lockoutDuration + - LockoutObservationWindow - A property of type System.TimeSpan, derived + from the directory attribute: lockoutObservationWindow + - LockoutThreshold - A property of type System.Int32, derived from the + directory attribute: lockoutThreshold + - MaxPasswordAge - A property of type System.TimeSpan, derived from the + directory attribute: maxPwdAge + - MinPasswordAge - A property of type System.TimeSpan, derived from the + directory attribute: minPwdAge + - MinPasswordLength - A property of type System.Int32, derived from the + directory attribute: minPwdLength + - PasswordHistoryCount - A property of type System.Int32, derived from the + directory attribute: pwdHistoryLength + - ReversibleEncryptionEnabled - A property of type System.Boolean, derived + from the directory attribute: pwdProperties + - ADForest - Represents a Active Directory forest in AD DS or a Configuration + Set in AD LDS and is derived from ADEntity. This class is not supported by + AD LDS. An ADForest may contain the following properties in addition to + those inherited from its parent. + - ApplicationPartitions - A property of type System.String, derived from + the directory attribute: ApplicationPartitions + - CrossForestReferences - A property of type System.String, derived from + the directory attribute: CrossForestReferences + - DomainNamingMaster - A property of type System.String, derived from the + directory attribute: DomainNamingMaster + - Domains - A property of type System.String, derived from the directory + attribute: Domains + - ForestMode - A property of type System.Int32, derived from the directory + attribute: msDS-Behavior-Version + - GlobalCatalogs - A property of type System.String, derived from the + directory attribute: GlobalCatalogs + - Name - A property of type System.String, derived from the directory + attribute: name + - PartitionContainerName - A property of type System.String, derived from + the directory attribute: distinguishedName + - RootDomain - A property of type System.String, derived from the directory + attribute: RootDomain + - SchemaMaster - A property of type System.String, derived from the + directory attribute: SchemaMaster + - Sites - A property of type System.String, derived from the directory + attribute: Sites + - SPNSuffixes - A property of type System.String, derived from the + directory attribute: msDS-SPNSuffixes + - UPNSuffixes - A property of type System.String, derived from the + directory attribute: uPNSuffixes + - ADDirectoryServer - Represents a directory server used as either a domain + controller or an AD LDS instance and is derived from ADEntity. An + ADDirectoryServer may contain the following properties in addition to those + inherited from its parent. + - DefaultPartition - A property of type System.String, derived from the + directory attribute: DefaultPartition + - HostName - A property of type System.String, derived from the directory + attribute: HostName + - InvocationId - A property of type System.Guid, derived from the directory + attribute: InvocationId + - IPv4Address - A property of type System.String, derived from the + directory attribute: HostName + - IPv6Address - A property of type System.String, derived from the + directory attribute: HostName + - LdapPort - A property of type System.Int32, derived from the directory + attribute: LdapPort + - Name - A property of type System.String, derived from the directory + attribute: Name + - NTDSSettingsObjectDN - A property of type System.String, derived from the + directory attribute: NTDSSettingsObjectDN + - OperationMasterRoles - A property of type + Microsoft.ActiveDirectory.Management.ADOperationMasterRole, derived from + the directory attribute: OperationMasterRole + - Partitions - A property of type System.String, derived from the directory + attribute: Partitions + - ServerObjectDN - A property of type System.String, derived from the + directory attribute: ServerObjectDN + - ServerObjectGuid - A property of type System.Guid, derived from the + directory attribute: ServerObjectGuid + - Site - A property of type System.String, derived from the directory + attribute: Site + - SslPort - A property of type System.Int32, derived from the directory + attribute: SslPort + - ADDomainController - Represents a domain controller in AD DS and is + derived from ADDirectoryServer. An ADDomainController may contain the + following properties in addition to those inherited from its parent. + - ComputerObjectDN - A property of type System.String, derived from the + directory attribute: ComputerDN + - Domain - A property of type System.String, derived from the directory + attribute: Domain + - Enabled - A property of type System.Boolean, derived from the directory + attribute: Enabled + - Forest - A property of type System.String, derived from the directory + attribute: Forest + - IsGlobalCatalog - A property of type System.Boolean, derived from the + directory attribute: IsGlobalCatalog + - IsReadOnly - A property of type System.Boolean, derived from the + directory attribute: IsReadOnly + - OperatingSystem - A property of type System.String, derived from the + directory attribute: OSName + - OperatingSystemHotfix - A property of type System.String, derived from + the directory attribute: OSHotFix + - OperatingSystemServicePack - A property of type System.String, derived + from the directory attribute: OSServicepack + - OperatingSystemVersion - A property of type System.String, derived from + the directory attribute: OSVersion diff --git a/docset/winserver2012r2-ps/adfs/Get-AdfsRelyingPartyTrust.md b/docset/winserver2012r2-ps/adfs/Get-AdfsRelyingPartyTrust.md index a05cb1abf2..125efee035 100644 --- a/docset/winserver2012r2-ps/adfs/Get-AdfsRelyingPartyTrust.md +++ b/docset/winserver2012r2-ps/adfs/Get-AdfsRelyingPartyTrust.md @@ -44,7 +44,8 @@ This command gets the property settings for the relying party trust named Fabrik ### Example 2: Get property settings for a relying party trust by using an identifier ``` -PS C:\> Get-AdfsRelyingPartyTrust -Identifier "https://FabrikamApp.CentralServer.org" +PS C:\> Get-AdfsRelyingPartyTrust -Identifier "https://app.fabrikam.com" + ``` This command gets the property settings for a relying party trust that has the identifier `https://FabrikamApp.CentralServer.org`. diff --git a/docset/winserver2012r2-ps/hpc/Get-HpcJobCredential.md b/docset/winserver2012r2-ps/hpc/Get-HpcJobCredential.md index c56d39968a..cad340bedd 100644 --- a/docset/winserver2012r2-ps/hpc/Get-HpcJobCredential.md +++ b/docset/winserver2012r2-ps/hpc/Get-HpcJobCredential.md @@ -66,6 +66,6 @@ This cmdlet was introduced in HPC Pack 2008 R2 with Service Pack 2 (SP2). It is [New-HpcSoftCard](./New-HpcSoftCard.md) -[Remove-HpcJobCredential](./Remove-HpcJobCredential.md) +[Remove-HpcJobCredential](/powershell/module/hpcpack2016/remove-hpcjobcredential?view=hpc16-ps) -[Set-HpcJobCredential](./Set-HpcJobCredential.md) +[Set-HpcJobCredential](/powershell/module/hpcpack2016/set-hpcjobcredential?view=hpc16-ps) diff --git a/docset/winserver2012r2-ps/hpc/New-HpcSoftCard.md b/docset/winserver2012r2-ps/hpc/New-HpcSoftCard.md index 1bd67d39b9..2b451ecb29 100644 --- a/docset/winserver2012r2-ps/hpc/New-HpcSoftCard.md +++ b/docset/winserver2012r2-ps/hpc/New-HpcSoftCard.md @@ -85,4 +85,4 @@ This cmdlet supports the common parameters: -Debug, -ErrorAction, -ErrorVariable [Get-HpcJobCredential](./Get-HpcJobCredential.md) -[Set-HpcJobCredential](./Set-HpcJobCredential.md) +[Set-HpcJobCredential](/powershell/module/hpcpack2016/set-hpcjobcredential?view=hpc16-ps) diff --git a/docset/winserver2012r2-ps/hpc/Set-HpcNode.md b/docset/winserver2012r2-ps/hpc/Set-HpcNode.md index 66ed57e7df..493696be6a 100644 --- a/docset/winserver2012r2-ps/hpc/Set-HpcNode.md +++ b/docset/winserver2012r2-ps/hpc/Set-HpcNode.md @@ -340,11 +340,11 @@ You must be a cluster administrator to run this cmdlet successfully. ## RELATED LINKS -[Get-HpcNode](./Get-HpcNode.md) +[Get-HpcNode](/powershell/module/hpcpack2016/get-hpcnode?view=hpc16-ps) -[Remove-HpcNode](./Remove-HpcNode.md) +[Remove-HpcNode](/powershell/module/hpcpack2016/remove-hpcnode?view=hpc16-ps) -[Restart-HpcNode](./Restart-HpcNode.md) +[Restart-HpcNode](/powershell/module/hpcpack2016/restart-hpcnode?view=hpc16-ps) [Shutdown-HpcNode](./Shutdown-HpcNode.md) diff --git a/docset/winserver2012r2-ps/hpc/Set-HpcNodeState.md b/docset/winserver2012r2-ps/hpc/Set-HpcNodeState.md index dad527b258..36a98452df 100644 --- a/docset/winserver2012r2-ps/hpc/Set-HpcNodeState.md +++ b/docset/winserver2012r2-ps/hpc/Set-HpcNodeState.md @@ -214,6 +214,6 @@ You must be a cluster administrator to run this cmdlet successfully. ## RELATED LINKS -[Get-HpcNode](./Get-HpcNode.md) +[Get-HpcNode](/powershell/module/hpcpack2016/get-hpcnode?view=hpc16-ps) [Set-HpcNode](./Set-HpcNode.md) diff --git a/docset/winserver2012r2-ps/hpc/Set-HpcPool.md b/docset/winserver2012r2-ps/hpc/Set-HpcPool.md index 6bda893cfb..35ce446d7e 100644 --- a/docset/winserver2012r2-ps/hpc/Set-HpcPool.md +++ b/docset/winserver2012r2-ps/hpc/Set-HpcPool.md @@ -117,8 +117,8 @@ This cmdlet was introduced in HPC Pack 2008 R2 with Service Pack 2 (SP2). It is ## RELATED LINKS -[Add-HpcPool](./Add-HpcPool.md) +[Add-HpcPool](/powershell/module/hpcpack2016/add-hpcpool?view=hpc16-ps) -[Get-HpcPool](./Get-HpcPool.md) +[Get-HpcPool](/powershell/module/hpcpack2016/get-hpcpool?view=hpc16-ps) -[Remove-HpcPool](./Remove-HpcPool.md) +[Remove-HpcPool](/powershell/module/hpcpack2016/remove-hpcpool?view=hpc16-ps) diff --git a/docset/winserver2012r2-ps/hpc/Set-HpcSoaCredential.md b/docset/winserver2012r2-ps/hpc/Set-HpcSoaCredential.md index e47bd6b686..71110791bf 100644 --- a/docset/winserver2012r2-ps/hpc/Set-HpcSoaCredential.md +++ b/docset/winserver2012r2-ps/hpc/Set-HpcSoaCredential.md @@ -132,8 +132,8 @@ This cmdlet supports the common parameters: -Debug, -ErrorAction, -ErrorVariable ## RELATED LINKS -[Remove-HpcSoaCredential](./Remove-HpcSoaCredential.md) +[Remove-HpcSoaCredential](/powershell/module/hpcpack2016/remove-hpcsoacredential?view=hpc16-ps) -[Set-HpcJobCredential](./Set-HpcJobCredential.md) +[Set-HpcJobCredential](/powershell/module/hpcpack2016/set-hpcjobcredential?view=hpc16-ps) [Set-HpcTestCredential](./Set-HpcTestCredential.md) diff --git a/docset/winserver2012r2-ps/hpc/Set-HpcTask.md b/docset/winserver2012r2-ps/hpc/Set-HpcTask.md index 6e3be5366a..4d58cca1b7 100644 --- a/docset/winserver2012r2-ps/hpc/Set-HpcTask.md +++ b/docset/winserver2012r2-ps/hpc/Set-HpcTask.md @@ -663,10 +663,10 @@ This cmdlet supports the common parameters: -Debug, -ErrorAction, -ErrorVariable ## RELATED LINKS -[Add-HpcTask](./Add-HpcTask.md) +[Add-HpcTask](/powershell/module/hpcpack2016/add-hpctask?view=hpc16-ps) -[Export-HpcTask](./Export-HpcTask.md) +[Export-HpcTask](/powershell/module/hpcpack2016/export-hpctask?view=hpc16-ps) -[Get-HpcTask](./Get-HpcTask.md) +[Get-HpcTask](/powershell/module/hpcpack2016/get-hpctask?view=hpc16-ps) [Stop-HpcTask](./Stop-HpcTask.md) diff --git a/docset/winserver2012r2-ps/hpc/Set-HpcTestCredential.md b/docset/winserver2012r2-ps/hpc/Set-HpcTestCredential.md index e5714a831d..1e414d29a3 100644 --- a/docset/winserver2012r2-ps/hpc/Set-HpcTestCredential.md +++ b/docset/winserver2012r2-ps/hpc/Set-HpcTestCredential.md @@ -144,10 +144,10 @@ This cmdlet supports the common parameters: -Debug, -ErrorAction, -ErrorVariable ## RELATED LINKS -[Invoke-HpcTest](./Invoke-HpcTest.md) +[Invoke-HpcTest](/powershell/module/hpcpack2016/invoke-hpctest?view=hpc16-ps) -[Remove-HpcTestCredential](./Remove-HpcTestCredential.md) +[Remove-HpcTestCredential](/powershell/module/hpcpack2016/remove-hpctestcredential?view=hpc16-ps) -[Set-HpcJobCredential](./Set-HpcJobCredential.md) +[Set-HpcJobCredential](/powershell/module/hpcpack2016/set-hpcjobcredential?view=hpc16-ps) [Set-HpcSoaCredential](./Set-HpcSoaCredential.md) diff --git a/docset/winserver2012r2-ps/hpc/Shutdown-HpcNode.md b/docset/winserver2012r2-ps/hpc/Shutdown-HpcNode.md index da3c77aeda..1388c718a6 100644 --- a/docset/winserver2012r2-ps/hpc/Shutdown-HpcNode.md +++ b/docset/winserver2012r2-ps/hpc/Shutdown-HpcNode.md @@ -165,11 +165,11 @@ This cmdlet supports the common parameters: -Debug, -ErrorAction, -ErrorVariable ## RELATED LINKS -[Get-HpcNode](./Get-HpcNode.md) +[Get-HpcNode](/powershell/module/hpcpack2016/get-hpcnode?view=hpc16-ps) -[Remove-HpcNode](./Remove-HpcNode.md) +[Remove-HpcNode](/powershell/module/hpcpack2016/remove-hpcnode?view=hpc16-ps) -[Restart-HpcNode](./Restart-HpcNode.md) +[Restart-HpcNode](/powershell/module/hpcpack2016/restart-hpcnode?view=hpc16-ps) [Set-HpcNode](./Set-HpcNode.md) diff --git a/docset/winserver2012r2-ps/hpc/Start-HpcAzureNode.md b/docset/winserver2012r2-ps/hpc/Start-HpcAzureNode.md index a9377a3e62..c57a95dc86 100644 --- a/docset/winserver2012r2-ps/hpc/Start-HpcAzureNode.md +++ b/docset/winserver2012r2-ps/hpc/Start-HpcAzureNode.md @@ -137,7 +137,7 @@ This cmdlet supports the common parameters: -Debug, -ErrorAction, -ErrorVariable ## RELATED LINKS -[Remove-HpcAzureNode](./Remove-HpcAzureNode.md) +[Remove-HpcAzureNode](/powershell/module/hpcpack2016/remove-hpcazurenode?view=hpc16-ps) [Start-HpcNodeSet](./Start-HpcNodeSet.md) diff --git a/docset/winserver2012r2-ps/hpc/Start-HpcNode.md b/docset/winserver2012r2-ps/hpc/Start-HpcNode.md index 94f1ca3c3d..292913cce6 100644 --- a/docset/winserver2012r2-ps/hpc/Start-HpcNode.md +++ b/docset/winserver2012r2-ps/hpc/Start-HpcNode.md @@ -117,11 +117,11 @@ This cmdlet supports the common parameters: -Debug, -ErrorAction, -ErrorVariable ## RELATED LINKS -[Get-HpcNode](./Get-HpcNode.md) +[Get-HpcNode](/powershell/module/hpcpack2016/get-hpcnode?view=hpc16-ps) -[Remove-HpcNode](./Remove-HpcNode.md) +[Remove-HpcNode](/powershell/module/hpcpack2016/remove-hpcnode?view=hpc16-ps) -[Restart-HpcNode](./Restart-HpcNode.md) +[Restart-HpcNode](/powershell/module/hpcpack2016/restart-hpcnode?view=hpc16-ps) [Set-HpcNode](./Set-HpcNode.md) diff --git a/docset/winserver2012r2-ps/hpc/Start-HpcNodeSet.md b/docset/winserver2012r2-ps/hpc/Start-HpcNodeSet.md index d098ba88e5..a9ec139858 100644 --- a/docset/winserver2012r2-ps/hpc/Start-HpcNodeSet.md +++ b/docset/winserver2012r2-ps/hpc/Start-HpcNodeSet.md @@ -111,9 +111,9 @@ This cmdlet supports the common parameters: -Debug, -ErrorAction, -ErrorVariable ## RELATED LINKS -[Add-HpcNodeSet](./Add-HpcNodeSet.md) +[Add-HpcNodeSet](/powershell/module/hpcpack2016/add-hpcnodeset?view=hpc16-ps) -[Remove-HpcNodeSet](./Remove-HpcNodeSet.md) +[Remove-HpcNodeSet](/powershell/module/hpcpack2016/remove-hpcnodeset?view=hpc16-ps) [Start-HpcAzureNode](./Start-HpcAzureNode.md) diff --git a/docset/winserver2012r2-ps/hpc/Stop-HpcAzureNode.md b/docset/winserver2012r2-ps/hpc/Stop-HpcAzureNode.md index 159055cdda..3a58d98efa 100644 --- a/docset/winserver2012r2-ps/hpc/Stop-HpcAzureNode.md +++ b/docset/winserver2012r2-ps/hpc/Stop-HpcAzureNode.md @@ -171,7 +171,7 @@ This cmdlet supports the common parameters: -Debug, -ErrorAction, -ErrorVariable ## RELATED LINKS -[Remove-HpcAzureNode](./Remove-HpcAzureNode.md) +[Remove-HpcAzureNode](/powershell/module/hpcpack2016/remove-hpcazurenode?view=hpc16-ps) [Start-HpcAzureNode](./Start-HpcAzureNode.md) diff --git a/docset/winserver2012r2-ps/hpc/Stop-HpcJob.md b/docset/winserver2012r2-ps/hpc/Stop-HpcJob.md index e02a6b7de0..0a49dc21b5 100644 --- a/docset/winserver2012r2-ps/hpc/Stop-HpcJob.md +++ b/docset/winserver2012r2-ps/hpc/Stop-HpcJob.md @@ -248,12 +248,12 @@ All other tasks are queued, including those that failed. ## RELATED LINKS -[Export-HpcJob](./Export-HpcJob.md) +[Export-HpcJob](/powershell/module/hpcpack2016/export-hpcjob?view=hpc16-ps) -[Get-HpcJob](./Get-HpcJob.md) +[Get-HpcJob](/powershell/module/hpcpack2016/get-hpcjob?view=hpc16-ps) -[New-HpcJob](./New-HpcJob.md) +[New-HpcJob](/powershell/module/hpcpack2016/new-hpcjob?view=hpc16-ps) -[Set-HpcJob](./Set-HpcJob.md) +[Set-HpcJob](/powershell/module/hpcpack2016/set-hpcjob?view=hpc16-ps) [Submit-HpcJob](./Submit-HpcJob.md) diff --git a/docset/winserver2012r2-ps/hpc/Stop-HpcNodeSet.md b/docset/winserver2012r2-ps/hpc/Stop-HpcNodeSet.md index 2c4730b185..4057ab08a6 100644 --- a/docset/winserver2012r2-ps/hpc/Stop-HpcNodeSet.md +++ b/docset/winserver2012r2-ps/hpc/Stop-HpcNodeSet.md @@ -143,9 +143,9 @@ This cmdlet supports the common parameters: -Debug, -ErrorAction, -ErrorVariable ## RELATED LINKS -[Add-HpcNodeSet](./Add-HpcNodeSet.md) +[Add-HpcNodeSet](/powershell/module/hpcpack2016/add-hpciscsistoragearray?view=hpc16-ps) -[Remove-HpcNodeSet](./Remove-HpcNodeSet.md) +[Remove-HpcNodeSet](/powershell/module/hpcpack2016/remove-hpcnodeset?view=hpc16-ps) [Start-HpcNodeSet](./Start-HpcNodeSet.md) diff --git a/docset/winserver2012r2-ps/hpc/Stop-HpcTask.md b/docset/winserver2012r2-ps/hpc/Stop-HpcTask.md index 35f45ee854..bdca199231 100644 --- a/docset/winserver2012r2-ps/hpc/Stop-HpcTask.md +++ b/docset/winserver2012r2-ps/hpc/Stop-HpcTask.md @@ -257,11 +257,11 @@ This cmdlet supports the common parameters: -Debug, -ErrorAction, -ErrorVariable ## RELATED LINKS -[Add-HpcTask](./Add-HpcTask.md) +[Add-HpcTask](/powershell/module/hpcpack2016/add-hpctask?view=hpc16-ps) -[Export-HpcTask](./Export-HpcTask.md) +[Export-HpcTask](/powershell/module/hpcpack2016/export-hpctask?view=hpc16-ps) -[Get-HpcTask](./Get-HpcTask.md) +[Get-HpcTask](/powershell/module/hpcpack2016/get-hpctask?view=hpc16-ps) [Set-HpcTask](./Set-HpcTask.md) diff --git a/docset/winserver2012r2-ps/hpc/Stop-HpcTestResult.md b/docset/winserver2012r2-ps/hpc/Stop-HpcTestResult.md index 758d5f24d1..dab03b7c8c 100644 --- a/docset/winserver2012r2-ps/hpc/Stop-HpcTestResult.md +++ b/docset/winserver2012r2-ps/hpc/Stop-HpcTestResult.md @@ -156,8 +156,8 @@ This cmdlet supports the common parameters: -Debug, -ErrorAction, -ErrorVariable ## RELATED LINKS -[Export-HpcTestResult](./Export-HpcTestResult.md) +[Export-HpcTestResult](/powershell/module/hpcpack2016/export-hpctestresult?view=hpc16-ps) -[Get-HpcTestResult](./Get-HpcTestResult.md) +[Get-HpcTestResult](/powershell/module/hpcpack2016/get-hpctestresult?view=hpc16-ps) -[Invoke-HpcTest](./Invoke-HpcTest.md) +[Invoke-HpcTest](/powershell/module/hpcpack2016/invoke-hpctest?view=hpc16-ps) diff --git a/docset/winserver2012r2-ps/hpc/Submit-HpcJob.md b/docset/winserver2012r2-ps/hpc/Submit-HpcJob.md index ba9ead48c8..71453f09be 100644 --- a/docset/winserver2012r2-ps/hpc/Submit-HpcJob.md +++ b/docset/winserver2012r2-ps/hpc/Submit-HpcJob.md @@ -126,12 +126,12 @@ This cmdlet supports the common parameters: -Debug, -ErrorAction, -ErrorVariable ## RELATED LINKS -[Export-HpcJob](./Export-HpcJob.md) +[Export-HpcJob](/powershell/module/hpcpack2016/export-hpcjob?view=hpc16-ps) -[Get-HpcJob](./Get-HpcJob.md) +[Get-HpcJob](/powershell/module/hpcpack2016/get-hpcjob?view=hpc16-ps) -[New-HpcJob](./New-HpcJob.md) +[New-HpcJob](/powershell/module/hpcpack2016/new-hpcjob?view=hpc16-ps) -[Set-HpcJob](./Set-HpcJob.md) +[Set-HpcJob](/powershell/module/hpcpack2016/set-hpcjob?view=hpc16-ps) [Stop-HpcJob](./Stop-HpcJob.md) diff --git a/docset/winserver2012r2-ps/hpc/Validate-HpcIScsiStorageArray.md b/docset/winserver2012r2-ps/hpc/Validate-HpcIScsiStorageArray.md index a58c7aa395..dab5cd8515 100644 --- a/docset/winserver2012r2-ps/hpc/Validate-HpcIScsiStorageArray.md +++ b/docset/winserver2012r2-ps/hpc/Validate-HpcIScsiStorageArray.md @@ -112,10 +112,10 @@ The message for this event provides more information about the failure. ## RELATED LINKS -[Add-HpcIScsiStorageArray](./Add-HpcIScsiStorageArray.md) +[Add-HpcIScsiStorageArray](/powershell/module/hpcpack2016/add-hpciscsistoragearray?view=hpc16-ps) -[Get-HpcIScsiStorageArray](./Get-HpcIScsiStorageArray.md) +[Get-HpcIScsiStorageArray](/powershell/module/hpcpack2016/get-hpciscsistoragearray?view=hpc16-ps) -[Remove-HpcIScsiStorageArray](./Remove-HpcIScsiStorageArray.md) +[Remove-HpcIScsiStorageArray](/powershell/module/hpcpack2016/remove-hpciscsistoragearray?view=hpc16-ps) -[Set-HpcIScsiStorageArray](./Set-HpcIScsiStorageArray.md) +[Set-HpcIScsiStorageArray](/powershell/module/hpcpack2016/set-hpciscsistoragearray?view=hpc16-ps) diff --git a/docset/winserver2012r2-ps/hyper-v/Get-VMNetworkAdapter.md b/docset/winserver2012r2-ps/hyper-v/Get-VMNetworkAdapter.md index 88e0c19d8b..50aa2fb27b 100644 --- a/docset/winserver2012r2-ps/hyper-v/Get-VMNetworkAdapter.md +++ b/docset/winserver2012r2-ps/hyper-v/Get-VMNetworkAdapter.md @@ -167,7 +167,7 @@ Accept wildcard characters: False ### -VM Specifies the virtual machine whose virtual network adapters are to be retrieved. -. The asterisk, "*", is the wildcard. +The asterisk, "*", is the wildcard. If it is specified the cmdlet returns virtual network adapters from every virtual machine in the system. ```yaml diff --git a/docset/winserver2016-ps/activedirectory/About/About.md b/docset/winserver2016-ps/activedirectory/About/About.md new file mode 100644 index 0000000000..449df28850 --- /dev/null +++ b/docset/winserver2016-ps/activedirectory/About/About.md @@ -0,0 +1,26 @@ +--- +description: About articles for the ActiveDirectory module. +Help Version: 3.1.0.0 +Locale: en-US +ms.date: 07/03/2024 +title: About articles +--- +# About topics + +## Description + +About topics cover a range of concepts about PowerShell. + +## About Topics + +### [about_ActiveDirectory](about_ActiveDirectory.md) +The Active Directory module is a command line interface for managing Active Directory. + +### [about_ActiveDirectory_Filter](about_ActiveDirectory_Filter.md) +Describes the syntax and behavior of the search filter supported by the Active Directory module for Windows PowerShell. + +### [about_ActiveDirectory_Identity](about_ActiveDirectory_Identity.md) +The Active Directory module for Windows PowerShell objects have a range of identifying attributes that are used for search and retrieval. + +### [about_ActiveDirectory_ObjectModel](about_ActiveDirectory_ObjectModel.md) +Describes the object model of the Active Directory module for Windows PowerShell. diff --git a/docset/winserver2016-ps/activedirectory/About/about_ActiveDirectory.md b/docset/winserver2016-ps/activedirectory/About/about_ActiveDirectory.md new file mode 100644 index 0000000000..1b7183dcd2 --- /dev/null +++ b/docset/winserver2016-ps/activedirectory/About/about_ActiveDirectory.md @@ -0,0 +1,81 @@ +--- +title: about_ActiveDirectory +ms.date: 04/22/2013 +description: The Active Directory module is a command line interface for managing Active Directory. +Locale: en-US +schema: 2.0.0 +--- + +# about_ActiveDirectory + +## SHORT DESCRIPTION + +The Active Directory module is a command line interface for managing Active +Directory. + +## LONG DESCRIPTION + +The Active Directory module for Windows PowerShell is for IT Professionals who +are administering and interfacing with Active Directory. The Active Directory +module provides an efficient way to complete many administrative, +configuration, and diagnostic tasks across Active Directory Domain Services (AD +DS) and Active Directory Lightweight Directory Services (AD LDS) instances in +their environments. The Active Directory module includes a set of Windows +PowerShell cmdlets and a provider. The provider exposes the Active Directory +database through a hierarchical navigation system, which is very similar to the +file system. As with drives in a file system, such as C:, you can connect +Windows PowerShell drives to Active Directory domains and AD LDS, as well as +Active Directory snapshots. + +### Coverage of Active Directory Module Cmdlets + +Create, Read, Update, and Delete actions are supported for Active Directory +objects by cmdlets such as `New-ADUser`, `Get-ADOrganizationalUnit`, +`Set-ADComputer`, and `Remove-ADUser`. + +Account and Password Policy Management are supported by cmdlets such as +`Enable-ADAccount`, `Unlock-ADAccount`, `New-ADServiceAccount`, +`Set-ADAccountControl`, and `Remove-ADFineGrainedPasswordPolicy`. + +Domain and Forest Management is supported by cmdlets such as `Get-ADForest`, +`Set-ADForest`, `Set-ADForestMode`, `Enable-ADOptionalFeature`, +`Get-ADDomainController`, and `Get-ADDomain`. + +### Listing the Active Directory Module Cmdlets + +To get a list of all of the Active Directory module cmdlets, run + +```powershell +Get-Command -Module ActiveDirectory +``` + +### Getting Started + +Getting started with the Active Directory module for Windows PowerShell is as +easy as clicking the following shortcut: + +Run the following command in any Windows PowerShell prompt to import the Active +Directory module: + +```powershell +Import-Module ActiveDirectory +``` + +### Overview and Conceptual Topics + +The first two of these topics offer a high level overview of the Active +Directory module and the Active Directory Provider. + +- For a brief introduction to the Active Directory provider for Windows + PowerShell, see [ActiveDirectory](/powershell/module/activedirectory). +- The following topics are conceptual support topics for the Active Directory + module cmdlets. + - For an introduction to the **Identity** parameter, which is used by the + Active Directory module cmdlets to identify objects in the directory, see + [about_ActiveDirectory_Identity](about_ActiveDirectory_Identity.md). + - For an introduction to the **Filter** parameter which is used by Active + Directory module cmdlets to search for objects in the directory, see + [about_ActiveDirectory_Filter](about_ActiveDirectory_Filter.md). + - For an introduction to the .NET Framework-based object model implemented by + the Active Directory module, see + [about_ActiveDirectory_ObjectModel](about_ActiveDirectory_ObjectModel.md). diff --git a/docset/winserver2016-ps/activedirectory/About/about_ActiveDirectory_Filter.md b/docset/winserver2016-ps/activedirectory/About/about_ActiveDirectory_Filter.md new file mode 100644 index 0000000000..23a83c0a0a --- /dev/null +++ b/docset/winserver2016-ps/activedirectory/About/about_ActiveDirectory_Filter.md @@ -0,0 +1,351 @@ +--- +title: about_ActiveDirectory_Filter +ms.date: 04/22/2013 +description: Describes the syntax and behavior of the search filter supported by the Active Directory module for Windows PowerShell. +Locale: en-US +schema: 2.0.0 +--- + +# about_ActiveDirectory_Filter + +## SHORT DESCRIPTION + +Describes the syntax and behavior of the search filter supported by the Active +Directory module for Windows PowerShell. + +## LONG DESCRIPTION + +Most get-AD* Active Directory module cmdlets use the Filter parameter to search +for objects. The Filter parameter has been implemented to replace the function +of the LDAP Filter and adds support for PowerShell variables, rich data types, +improved error checking and an Active Directory extended form of the PowerShell +Expression Language. + + +- Support for LDAP Filter Syntax + + The LDAP filter syntax is supported through the **LDAPFilter** parameter. You + will find LDAP filter examples along with the new Active Directory module + filter examples in the Filter Examples section of this topic. + + +- Search Breadth and Depth + + The breadth and depth of your filter-driven search can be modified by two + Active Directory module cmdlet parameters: **SearchBase** and **SearchScope**. + + When within the context of the Active Directory provider, if the + **Searchbase** parameter is not specified, **SearchBase** will default to the + current path. When not running under the Active Directory provider, the + **SearchBase** will default to the server's **DefaultNamingContext**. + + The **SearchScope** parameter defaults to the value `Subtree`, of the + enumerated type **ADSearchScope**. + + For more information, see the **SearchBase** and **SearchScope** parameter + descriptions on any `Get-AD*` cmdlet. + +- Search Result Behavior + + The behavior of the Active Directory module when returning results of a + search is modified by two cmdlet parameters: **ResultPageSize** and + **ResultSetSize**. + + **ResultSetSize** controls the maximum number of returned objects. + + **ResultPageSize** specifies the maximum number of objects for each returned + page of information. + + See the **ResultPageSize** and **ResultSetSize** parameter descriptions on + any `Get-AD*` cmdlet for more information. + + +- Timeout Behavior + + The following statements specify timeout conditions within the Active + Directory module and describe what can be done about a timeout them. + + The default Active Directory module timeout for all operations is 2 + minutes. + + For search operation, the Active Directory module uses paging control + with a 2-minute timeout for each page search. + + > [!NOTE] + > Because a search may involve multiple server page requests the overall + > search time may exceed 2 minutes. + + A **TimeoutException** error indicates that a timeout has occurred. + + For a search operation, you can choose to use a smaller page size, set with + the **ResultPageSize** parameter, if you are getting a **TimeoutException** + error. + + If after trying these changes you are still getting a **TimeoutException** + error, consider optimizing your filter using the guidance in the + Optimizing Filters section of this topic. + + +- Optimizing Filters + + You can enhance the search filter behavior by using these guidelines. + + - Avoid using the **Recursive** parameter as it intensifies resource usage of + the search operation. + - Avoid using bitwise AND operators and bitwise OR operators. For more + information, see the Supported Operators section of this topic. + - Avoid using the logical NOT operator. + - Break down your search into multiple queries with narrower conditions. + + For a full description of filter syntax and usage, see the Filter Syntax + section of this topic. + + +## Filter Examples + +The following section shows many examples of filter use in common queries. + +### Example 1 - Get all entries: + +- LDAP Filter Equivalent: `(objectClass=*)` + +```powershell +Get-ADObject -Filter 'ObjectClass -like "*"' +``` + +### Example 2 - Get entries containing "bob" somewhere in the common name + +- LDAP Filter Equivalent: `(cn=*bob*)` + +```powershell +Get-ADObject -Filter 'CN -like "*bob*"' +``` + +### Example 3 - Get entries with a bad password count greater than five + +- LDAP Filter Equivalent: `(&(!badpwdcount<=5)(badpwdcount=*))` + +```powershell +Get-ADUser -Filter 'badpwdcount -ge 5' +``` + +### Example 4 - Get all users with an e-mail attribute + +- LDAP Filter Equivalent: `(&(objectClass=user)(email=*))` + +```powershell +Get-ADUser -filter 'email -like "*"' +``` + +-or- + +```powershell +Get-ADObject -filter 'email -like "*" -and ObjectClass -eq "user"' +``` + +### Example 5 - Get all user entries with an e-mail attribute and a surname equal to "smith": + +- LDAP Filter Equivalent: `(&(sn=smith)(objectClass=user)(email=*))` + +```powershell +Get-ADUser -Filter 'Email -like "*" -and SurName -eq "smith"' +``` + +-or- + +```powershell +Get-ADUser -Filter 'Email -like "*" -and sn -eq "smith"' +``` + + +### Example 6 - Get all user entries with a common name that starts with "andy" and users with a common name of "steve" or "margaret" + +- LDAP Filter Equivalent: `(&(objectClass=user) | (cn=andy*)(cn=steve)(cn=margaret))` + +```powershell +Get-ADUser -Filter 'CN -like "andy*" -or CN -eq "steve" -or CN -eq "margaret"' +``` + + +This example demonstrates a more complex logic and the use of precedence +control via parenthesis. + +```powershell +Get-ADObject -Filter 'objectClass -eq "user" -and (CN -like "andy*" -or CN -eq "steve" -or CN -eq "margaret")' +``` + +### Example 7 - Get all entries without an e-mail attribute + +- LDAP Filter Equivalent: `(!(email=*))` + +```powershell +Get-ADUser -Filter '-not Email -like "*"' +``` + +-or- + +```powershell +Get-ADUser -Filter 'Email -notlike "*"' +``` + +### Example 8 - Get all users who did not logon since January 1, 2007 + +- LDAP Filter Equivalent: `(&(lastlogon<=X)(objectClass=user))` where X is + number of 100-nanosecond slices since Jan 1st 1601 + +```powershell +$date = new-object System.DateTime -ArgumentList @(2007,1,1,0,0,0) +Get-ADUser -Filter '-not LastLogon -le $date' +``` + +### Example 9 - Get all users who have logged on in the last 5 days + +- LDAP Filter Equivalent: + + ``` + (&(lastLogon>=128812906535515110) + (objectClass=user)(!(objectClass=computer))) + ``` + +```powershell +$date = (get-date) - (new-timespan -days 5) +Get-ADUser -Filter 'lastLogon -gt $date' +``` + +### Example 10 - Search for group objects that have the ADS_GROUP_TYPE_SECURITY_ENABLED flag set + +- LDAP Filter Equivalent: + `(&(objectCategory=group)(groupType:1.2.840.113556.1.4.803:=2147483648))` + +The following example query string searches for group objects that have the +ADS_GROUP_TYPE_SECURITY_ENABLED flag set. Be aware that the decimal value of +ADS_GROUP_TYPE_SECURITY_ENABLED (0x80000000 = 2147483648) is used for the +comparison value. + +```powershell +Get-ADGroup -filter 'groupType -band 0x80000000' +``` + +### Example 11 - Search the ancestry of an object + +- LDAP Filter Equivalent: + `(memberof:1.2.840.113556.1.4.1941:=(cn=Group1,OU=groupsOU,DC=x)))` + +The LDAP_MATCHING_RULE_IN_CHAIN is a matching rule OID that is designed to +provide a method to look up the ancestry of an object. Many applications using +Active Directory and AD LDS usually work with hierarchical data, which is +ordered by parent-child relationships. Previously, applications performed +transitive group expansion to figure out group membership, which used a lot of +network bandwidth. Applications made multiple round-trips to figure out if an +object fell "in the chain" if a link were traversed through to the end. + +An example of such a query is one designed to check if a user, "user1" is a +member of group "group1". "user1" may not be a direct member of group1. It +could be a member of some other group, which is a member of "group1". + +You would set the base to the user DN and the scope to base, and use the query: + +```powershell +Get-ADUser -Filter 'memberOf -RecursiveMatch "CN=Administrators, CN=Builtin,DC=Fabrikam,DC=com"' -SearchBase "CN=Administrator,CN=Users,DC=Fabrikam,DC=com" +``` + +## Filter Syntax + +The following syntax descriptions use Backus-Naur form to show the PowerShell +Expression Language for the Filter parameter. + +```Syntax + ::= "{" "}" + + ::= | + | + + + ::= | + "(" ")" + + ::= "-eq" | "-le" | "-ge" | "-ne" | "-lt" | "-gt" | + "-approx" | "-bor" | "-band" | "-recursivematch" | "-like" | + "-notlike" + + ::= "-and" | "-or" + + ::= "-not" + + ::= | + +::= < this value will be compared to the object data for + attribute using the specified filter operator +``` + + +## Supported Operators + +The following table shows frequently used search filter operators. + +| Operator | Description | LDAP Equivalent | +| ----------------- | -------------------------------------- | -------------------------- | +| `-eq` | Equal to. Wildcards not supported. | = | +| `-ne` | Not equal to. Wildcards not supported. | !x = y | +| `-approx` | Approximately equal to | ~= | +| `-le` | Lexicographically less than | <= | +| | or equal to | | +| `-lt` | Lexicographically less than | !x >= y | +| `-ge` | Lexicographically greater | >= | +| | than or equal to | | +| `-gt` | Lexicographically greater than | !x <= y | +| | | | +| `-and` | AND | & | +| `-or` | OR | | +| `-not` | NOT | ! | +| `-bor` | Bitwise OR | :1.2.840.113556.1.4.804:= | +| `-band` | Bitwise AND | :1.2.840.113556.1.4.803:= | +| `-recursivematch` | Use LDAP_MATCHING_RULE_IN_CHAIN | :1.2.840.113556.1.4.1941:= | +| `-like` | Similar to `-eq` and supports | = | +| | wildcard comparison. The only | | +| | wildcard character supported is: `*` | | +| `-notlike` | Not like. Supports wild | !x = y | +| | card comparison. | | + +> [!NOTE] +> PowerShell wildcards, other than "*", such as "?" are not supported by the +> **Filter** parameter syntax. + +### Operator Precedence + +The following listing shows the precedence of operators for filters from +highest to lowest. + +- Highest precedence: `-eq`, `-ge`, `-le`, `-approx`, `-band`, `-bor`, + `-recursivematch`, `-ne`, `-like`, `-not`, `-and` +- Lowest precedence: `-or` + +### Special Characters + +The following escape sequence should be used for specifying special characters +in AD Filter STRING data, that is, data enclosed in double or single quotes. + +| ASCII Character | Escape sequence substitute | +| --------------- | --------------------------------------------------- | +| `"` | `` `" `` (This escape sequence is only required if | +| | STRING data is enclosed in double quotes.) | +| `'` | `''` (This escape sequence is only required if | +| | STRING data is enclosed in single quotes.) | +| NUL | `\00` (This is a standard LDAP escape sequence.) | +| `\` | `\5c` (This is a standard LDAP escape sequence.) | + +### LDAP Special Characters + +ADFilter parser will automatically convert all the below characters found in +STRING data, that is data enclosed in " " or ' ' to their LDAP escape sequence. +End users need not know about these LDAP escape sequence. + +| ASCII Character | Escape sequence substitute | +| --------------- | ----------------------------------------------- | +| `*` | `\2a` (Character `*` will only be converted in | +| | -eq and -ne comparisons Users should use | +| | -like and -notlike operators for wildcard | +| | comparison.) | +| `(` | `\28` | +| `)` | `\29` | +| `/` | `\2f` | diff --git a/docset/winserver2016-ps/activedirectory/About/about_ActiveDirectory_Identity.md b/docset/winserver2016-ps/activedirectory/About/about_ActiveDirectory_Identity.md new file mode 100644 index 0000000000..c007277b19 --- /dev/null +++ b/docset/winserver2016-ps/activedirectory/About/about_ActiveDirectory_Identity.md @@ -0,0 +1,196 @@ +--- +title: about_ActiveDirectory_Identity +ms.date: 04/22/2013 +description: This article lists the identifying attributes that are used for search and retrieval supported by the Active Directory module for Windows PowerShell. +Locale: en-US +schema: 2.0.0 +--- + +# about_ActiveDirectory_Identity + +## SHORT DESCRIPTION + +The Active Directory module for Windows PowerShell objects have a range of +identifying attributes that are used for search and retrieval. + +## LONG DESCRIPTION + +In order to identify the objects in Active Directory, each object has +attributes that can be used as identifiers. In the Active Directory module, the +value of the identity of an object can be passed using the Identity parameter. +Each object type has its own set of possible types and values for use by the +Identity parameter. See the detailed description of the Identity parameter of +the given cmdlet for more information about its usage. + +When searching with the Active Directory module cmdlets, the value of the +Identity parameter, along with the values of the Server and Partition +parameters, is used to uniquely identify a single object. The Server parameter +is used to locate which server to connect with. The Partition parameter further +narrows the search to a specific partition. The Identity parameter then +resolves to a single unique object in the partition. + +Note that using the Security Accounts Manager (SAM) Account Name +(**sAMAccountName**) when targeting a global catalog port, you will not find a +user in a different domain if you are using the Identity parameter + +If more than one object is found using identity resolution, the Active +Directory module throws an error. + +For more information about the Server and Partition parameters, see the help +topics for the individual cmdlets where they are used, such as `Get-ADUser`, by +typing: + +```powershell +Get-Help Get-ADUser +``` + +### Objects and Identities + +Each object has a list of attributes that can be used as an identity for that +object. Additionally, if the object inherits from another object, then the +parent object's identities can also be used as the child object's identities. +For more information on the Active Directory object hierarchy, see +[about_ActiveDirectory_ObjectModel](about_ActiveDirectory_ObjectModel.md). + +> [!NOTE] +> For Active Directory Provider cmdlets, only an object's 'Distinguished Name' +> or 'Relative Distinguished Name' can be used as the identity. For a list of +> Active Directory Provider cmdlets, see ActiveDirectory. + +### Identity Attributes + +The following is a list of identity attributes by object type. + +- ADAccount + - Distinguished Name + - GUID (objectGUID) + - Security Identifier (objectSid) + - SAM Account Name (sAMAccountName) + +- ADComputer + - Distinguished Name + - GUID (objectGUID) + - Security Identifier (objectSid) + - Security Accounts Manager Account Name (sAMAccountName) + +- ADDirectoryServer + - Name of the server object (name) + - For AD LDS instances the syntax of a name is `$` + - For other Active Directory instances, use the value of the name property. + - Distinguished Name of the NTDS Settings object + - Distinguished Name of the server object that represents the directory + server. + - GUID (objectGUID) of server object under the configuration partition. + - GUID (objectGUID) of NTDS settings object under the configuration partition + +- ADDomain + - Distinguished Name + - GUID + - Security Identifier + - DNS domain name + - NetBIOS domain name + +- ADDomainController + - GUID (objectGUID) + - IPV4Address + - Global IPV6Address + - DNS Host Name (dNSHostName) + - Name of the server object + - Distinguished Name of the NTDS Settings object + - Distinguished Name of the server object that represents the domain controller + - GUID of NTDS settings object under the configuration partition + - GUID of server object under the configuration partition + - Distinguished Name of the computer object that represents the domain controller. + +- ADFineGrainedPasswordPolicy + - Distinguished Name + - GUID (objectGUID) + - Name (name) + +- ADForest + - Fully qualified domain name + - DNS host name + - NetBIOS name + +- ADGroup + - Distinguished Name + - GUID (objectGUID) + - Security Identifier (objectSid) + - Security Accounts Manager (SAM) Account Name (sAMAccountName) + +- ADObject + - Distinguished Name + - GUID (objectGUID) + +- ADOptionalFeature + - Distinguished Name + - Name (name) + - Feature GUID (featureGUID) + - GUID (objectGUID) + +- ADOrganizationalUnit + - Distinguished Name + - GUID (objectGUID) + +- ADPrincipal + - Distinguished Name + - GUID (objectGUID) + - Security Identifier (objectSid) + - SAM Account Name (sAMAccountName) + +- ADServiceAccount + - Distinguished Name + - GUID (objectGUID) + - Security Identifier (objectSid) + - SAM Account Name (sAMAccountName) + +- ADUser + - Distinguished Name + - GUID (objectGUID) + - Security Identifier (objectSid) + - SAM User Name (sAMUserName) + + +### Identities Formats + +Active Directory module objects have a range of identity attributes. Below is a +list of these, their types and formats. + +- Distinguished Name + - Example: CN=SaraDavis,CN=Europe,CN=Users, DC=corp,DC=contoso,DC=com + +- DNS domain name + - Example: redmond.corp.contoso.com + +- DNS Host Name (dNSHostName) + - Example: corp-DC01.corp.contoso.com + +- Feature GUID (featureGUID) + - Example: 599c3d2e-f72d-4d20-8a88-030d99495f20 + +- Fully qualified domain name + - Example: corp.contoso.com + +- Global IPV6Address + - Example: 2001:4898:0:fff:200:5efe:157.59.132.61 + +- GUID (objectGUID) + - Example: 599c3d2e-f72d-4d20-8a88-030d99495f20 + +- IPV4Address + - Example:157.59.132.61 + +- NetBIOS domain name + - Example: redmond + +- Name of the server object + - Example: corp-DC01$ + +- SAM Account Name (sAMAccountName) + - Example: saradavisreports + +- Security Identifier (objectSid) + - Example: S-1-5-21-3165297888-301567370-576410423-1103 + +- Name + - Example: Recycle Bin Feature diff --git a/docset/winserver2016-ps/activedirectory/About/about_ActiveDirectory_ObjectModel.md b/docset/winserver2016-ps/activedirectory/About/about_ActiveDirectory_ObjectModel.md new file mode 100644 index 0000000000..8535a97464 --- /dev/null +++ b/docset/winserver2016-ps/activedirectory/About/about_ActiveDirectory_ObjectModel.md @@ -0,0 +1,595 @@ +--- +title: about_ActiveDirectory_ObjectModel +ms.date: 04/22/2013 +description: Describes the object model of the Active Directory module for Windows PowerShell. +Locale: en-US +schema: 2.0.0 +--- + +# about_ActiveDirectory_ObjectModel + +## SHORT DESCRIPTION +Describes the object model of the Active Directory module for Windows +PowerShell. + +## LONG DESCRIPTION + +This topic explains the Active Directory module classes and their properties +used to model actual Active Directory attributes. It also outlines the class +hierarchy constructed from its Active Directory counterpart. The object model +establishes a data foundation for all the operations supported by Active +Directory module cmdlets. + +### Class Hierarchy + +The following list shows the class hierarchy defined in the Active Directory +module object model, with class inheritance implied by indentation. This +inheritance model allows for Active Directory cmdlets to accept a range of +object types as input. This means, for example, that the cmdlet +Get-ADPrincipalGroupMembership can accept as input any of the following +objects: ADGroup, ADAccount, ADComputer, ADServiceAccount or ADUser. This works +because of the inheritance model and guarantees that an ADUser object has all +of the properties of an ADPrincipal object. + +``` +ADEntity + ADRootDSE + ADObject + ADFineGrainedPasswordPolicy + ADOptionalFeature + ADOrganizationalUnit + ADPartition + ADDomain + ADPrincipal + ADAccount + ADComputer + ADServiceAccount + ADUser + ADGroup + ADDefaultDomainPasswordPolicy + ADForest + ADDirectoryServer + ADDomainController +``` + +### Active Directory Module Classes + +The following listing shows every Active Directory module class from the class +hierarchy listing. Each class defines a set of properties, some of which are +LDAP attributes that are retrieved by default and some are new properties +created specifically for the Active Directory module. These new properties are +derived from one or more LDAP attributes as outlined in the class listings. + + +- ADEntity - The base level class from which all other classes are derived. + - ADRootDSE - Represents the rootDSE and is derived from ADEntity. An + ADRootDSE may contain the following properties in addition to those + inherited from its parent. + - ConfigurationNamingContext - A property of type System.String, derived + from the directory attribute ConfigurationNamingContext + - CurrentTime - A property of type System.DateTime, derived from the + directory attribute CurrentTime + - DefaultNamingContext - A property of type System.String, derived from the + directory attribute DefaultNamingContext + - DnsHostName - A property of type System.String, derived from the + directory attribute DnsHostName + - DomainControllerFunctionality - A property of type + ADDomainControllerMode, derived from the directory attribute + DomainControllerFunctionality + - DomainFunctionality - A property of type ADDomainMode, derived from the + directory attribute DomainFunctionality + - DsServiceName - A property of type System.String, derived from the + directory attribute DsServiceName + - ForestFunctionality - A property of type ADForestMode, derived from the + directory attribute ForestFunctionality + - GlobalCatalogReady - A property of type System.Boolean, derived from the + directory attribute GlobalCatalogReady + - HighestCommittedUSN - A property of type System.Long, derived from the + directory attribute HighestCommittedUSN + - LdapServiceName - A property of type System.String, derived from the + directory attribute LdapServiceName + - NamingContexts - A property of type System.String, derived from the + directory attribute NamingContexts + - RootDomainNamingContext - A property of type System.String, derived from + the directory attribute RootDomainNamingContext + - SchemaNamingContext - A property of type System.String, derived from the + directory attribute SchemaNamingContext + - ServerName - A property of type System.String, derived from the directory + attribute ServerName + - SubschemaSubentry - A property of type ADObject, derived from the + directory attribute SubschemaSubentry + - SupportedCapabilities - A property of type ADObjectIdentifier, derived + from the directory attribute SupportedCapabilities + - SupportedControl - A property of type ADObjectIdentifier, derived from + the directory attribute SupportedControl + - SupportedLDAPPolicies - A property of type System.String, derived from + the directory attribute SupportedLDAPPolicies + - SupportedLDAPVersion - A property of type System.Int, derived from the + directory attribute SupportedLDAPVersion + - SupportedRootDSEOperations - A property of type + ADPropertyValueCollection, derived from the directory attribute + SupportedRootDSEOperations + - SupportedSASLMechanisms - A property of type System.String, derived from + the directory attribute SupportedSASLMechanisms + - Syncronized - A property of type System.Boolean, derived from the + directory attribute IsSynchronized. + - ADObject - Represents any object in Active Directory and is derived from + ADEntity. An ADObject may contain the following properties in addition to + those inherited from its parent. + - CanonicalName - A property of type System.String, derived from the + directory attribute: canonicalName + - CN - A property of type System.String, derived from the directory + attribute: cn + - Created - A property of type System.DateTime, derived from the directory + attribute: createTimeStamp + - Deleted - A property of type System.Boolean, derived from the directory + attribute: isDeleted + - Description - A property of type System.String, derived from the + directory attribute: description + - DisplayName - A property of type System.String, derived from the + directory attribute: displayName + - DistinguishedName - A property of type System.String, derived from the + directory attribute: distinguishedName + - LastKnownParent - A property of type System.String, derived from the + directory attribute: lastKnownParent + - Modified - A property of type System.DateTime, derived from the directory + attribute: modifyTimeStamp + - Name - A property of type System.String, derived from the directory + attribute: name + - ObjectCategory - A property of type System.String, derived from the + directory attribute: objectCategory + - ObjectClass - A property of type System.String, derived from the + directory attribute: objectClass + - ObjectGUID - A property of type System.Guid, derived from the directory + attribute: objectGUID + - ProtectedFromAccidentalDeletion - A property of type System.Boolean, + derived from the directory attributes: nTSecurityDescriptor, + sdRightsEffective, instanceType, isDeleted + - ADFineGrainedPasswordPolicy Represents a fine grained password policy + object; that is, an AD object of type msDS-PasswordSettings in AD DS and + is derived from ADObject. This class is not supported by AD LDS. An + ADFineGrainedPasswordPolicy may contain the following properties in + addition to those inherited from its parent. + - AppliesTo - A property of type System.String, derived from the + directory attribute: msDS-PSOAppliesTo + - ComplexityEnabled - A property of type System.Boolean, derived from the + directory attribute: msDS-PasswordComplexityEnabled + - LockoutDuration - A property of type System.TimeSpan, derived from the + directory attribute: msDS-LockoutDuration + - LockoutObservationWindow - A property of type System.TimeSpan, derived + from the directory attribute: msDS-LockoutObservationWindow + - LockoutThreshold - A property of type System.Int32, derived from the + directory attribute: msDS-LockoutThreshold + - MaxPasswordAge - A property of type System.TimeSpan, derived from the + directory attribute: msDS-MaximumPasswordAge + - MinPasswordAge - A property of type System.TimeSpan, derived from the + directory attribute: msDS-MinimumPasswordAge + - MinPasswordLength - A property of type System.Int32, derived from the + directory attribute: msDS-MinimumPasswordLength + - PasswordHistoryCount - A property of type System.Int32, derived from + the directory attribute: msDS-PasswordHistoryLength + - Precedence - A property of type System.Int32, derived from the + directory attribute: msDS-PasswordSettingsPrecedence + - ReversibleEncryptionEnabled - A property of type System.Boolean, + derived from the directory attribute: + msDS-PasswordReversibleEncryptionEnabled + - ADOptionalFeature Represents an optional feature, an Active Directory + object of type msDS-OptionalFeature, and is derived from ADObject. An + ADOptionalFeaturemay contain the following properties in addition to + those inherited from its parent. + - EnabledScopes - A property of type System.String, derived from the + directory attribute: msDS-EnabledFeatureBL + - FeatureGUID - A property of type System.Guid, derived from the + directory attribute: msDS-OptionalFeatureGUID + - FeatureScope - A property of type System.Int32, derived from the + directory attribute: msDS-OptionalFeatureFlags + - IsDisableable - A property of type System.Boolean, derived from the + directory attribute: msDS-OptionalFeatureFlags + - RequiredDomainMode - A property of type + Microsoft.ActiveDirectory.Management.ADDomainMode, derived from the + directory attribute: msDS-RequiredDomainBehaviorVersion + - RequiredForestMode - A property of type + Microsoft.ActiveDirectory.Management.ADForestMode, derived from the + directory attribute: msDS-RequiredForestBehaviorVersion + - ADOrganizationalUnit Represents an organizationalUnit (OU) object and is + derived from ADObject. An ADOrganizationalUnit may contain the following + properties in addition to those inherited from its parent. + - City - A property of type System.String, derived from the directory + attribute: l + - Country - A property of type System.String, derived from the directory + attribute: c + - LinkedGroupPolicyObjects - A property of type System.String, derived + from the directory attribute: gpLink. This property is not supported on + AD LDS. + - ManagedBy - A property of type System.String, derived from the + directory attribute: managedBy + - PostalCode - A property of type System.String, derived from the + directory attribute: postalCode + - State - A property of type System.String, derived from the directory + attribute: st + - StreetAddress - A property of type System.String, derived from the + directory attribute: street + - ADPartition - Represents a naming context, Configuration, Schema, Domain + or Application Partition(ND NC) and is derived from ADObject. This class + is not supported by AD LDS. An ADPartition may contain the following + properties in addition to those inherited from its parent. + - DeletedObjectsContainer - A property of type System.String, derived + from the directory attribute: DeletedObjectsContainer + - DNSRoot - A property of type System.String, derived from the directory + attribute: DNSRoot + - LostAndFoundContainer - A property of type System.String, derived from + the directory attribute: LostAndFoundContainer + - QuotasContainer - A property of type System.String, derived from the + directory attribute: QuotasContainer + - ReadOnlyReplicaDirectoryServers - A property of type System.String, + derived from the directory attribute: ReadOnlyReplicaDirectoryServers + - ReplicaDirectoryServers - A property of type System.String, derived + from the directory attribute: ReplicaDirectoryServers + - SubordinateReferences - A property of type System.String, derived from + the directory attribute: SubordinateReferences + - ADDomain - Represents a domain in AD DS or an instance in AD LDS; for + example, an Active Directory object of type domainDNS and is derived + from ADPartition. This class is not supported by AD LDS. An ADDomain + may contain the following properties in addition to those inherited + from its parent. + - AllowedDNSSuffixes - A property of type System.String, derived from + the directory attribute: msDS-AllowedDNSSuffixes + - ChildDomains - A property of type System.String, derived from the + directory attribute: ChildDomains + - ComputersContainer - A property of type System.String, derived from + the directory attribute: ComputersContainer + - DomainControllersContainer - A property of type System.String, + derived from the directory attribute: DomainControllersContainer + - DomainMode - A property of type System.Int32, derived from the + directory attribute: msDS-Behavior-Version + - DomainSID - A property of type + System.Security.Principal.SecurityIdentifier, derived from the + directory attribute: objectSid + - ForeignSecurityPrincipalsContainer - A property of type + System.String, derived from the directory attribute: + ForeignSecurityPrincipalsContainer + - Forest - A property of type System.String, derived from the directory + attribute: Forest + - InfrastructureMaster - A property of type System.String, derived from + the directory attribute: InfrastructureMaster + - LastLogonReplicationInterval - A property of type System.TimeSpan, + derived from the directory attribute: msDS-LogonTimeSyncInterval + - LinkedGroupPolicyObjects - A property of type System.String, derived + from the directory attribute: LinkedGroupPolicyObjects + - ManagedBy - A property of type System.String, derived from the + directory attribute: managedBy + - NetBIOSName - A property of type System.String, derived from the + directory attribute: NetBIOSName + - ParentDomain - A property of type System.String, derived from the + directory attribute: ParentDomain + - PDCEmulator - A property of type System.String, derived from the + directory attribute: PDCEmulator + - RIDMaster - A property of type System.String, derived from the + directory attribute: RIDMaster + - SystemsContainer - A property of type System.String, derived from the + directory attribute: SystemsContainer + - UsersContainer - A property of type System.String, derived from the + directory attribute: UsersContainer + - ADPrincipal - Represents a security principal, which is an Active + Directory object of type user, computer, group or iNetOrgPerson and is + derived from ADObject. An ADPrincipal may contain the following + properties in addition to those inherited from its parent. + - HomePage - A property of type System.String, derived from the + directory attribute: wWWHomePage + - MemberOf - A property of type System.String, derived from the + directory attribute: memberOf + - SamAccountName - A property of type System.String, derived from the + directory attribute: sAMAccountName. This property is not supported + for AD LDS. + - SID - A property of type + System.Security.Principal.SecurityIdentifier, derived from the + directory attribute: objectSid + - SIDHistory - A property of type + System.Security.Principal.SecurityIdentifier, derived from the + directory attribute: sIDHistory. This property is not supported for + AD LDS. + - ADAccount - Represents a security account; that is, an Active + Directory object of type user, computer or iNetOrgPerson and is + derived from ADPrincipal. An ADAccount may contain the following + properties in addition to those inherited from its parent. + - AccountExpirationDate - A property of type System.DateTime, derived + from the directory attribute: accountExpires + - AccountLockoutTime - A property of type System.DateTime, derived + from the directory attribute: lockoutTime + - AccountNotDelegated - A property of type System.Boolean, derived + from the directory attributes: userAccountControl, + msDS-User-Account-Control-Computed. This property is not supported + by AD LDS. + - AllowReversiblePasswordEncryption - A property of type + System.Boolean, for AD DS it is derived from the directory + attribute: userAccountControl; for AD LDS it is derived from the + directory attribute: ms-DS-UserEncryptedTextPasswordAllowed + - BadLogonCount - A property of type System.Int32, derived from the + directory attribute: badPwdCount + - CannotChangePassword - A property of type System.Boolean, derived + from the directory attribute: nTSecurityDescriptor + - Certificates - A property of type + System.Security.Cryptography.X509Certificates.X509Certificate, + derived from the directory attribute: userCertificate + - DoesNotRequirePreAuth - A property of type System.Boolean, derived + from the directory attributes: userAccountControl, + msDS-User-Account-Control-Computed. This property is not supported + by AD LDS. + - Enabled - A property of type System.Boolean, for AD DS it is + derived from the directory attributes: userAccountControl, + msDS-User-Account-Control-Computed; for AD LDS it is derived from + the directory attribute msDS-UserAccountDisabled + - HomedirRequired - A property of type System.Boolean, derived from + the directory attributes: userAccountControl, + msDS-User-Account-Control-Computed. This property is not supported + by AD LDS. + - LastBadPasswordAttempt - A property of type System.DateTime, + derived from the directory attribute: badPasswordTime + - LastLogonDate - A property of type System.DateTime, derived from + the directory attribute: lastLogonTimestamp + - LockedOut - A property of type System.Boolean, for AD DS it is + derived from the directory attributes: userAccountControl, + msDS-User-Account-Control-Computed, lockoutTime; for AD LDS it is + derived from the directory attribute msDS-UserAccountDisabled + - MNSLogonAccount - A property of type System.Boolean, derived from + the directory attributes: userAccountControl, + msDS-User-Account-Control-Computed. This property is not supported + by AD LDS. + - PasswordExpired - A property of type System.Boolean, for AD DS it + is derived from the directory attributes: userAccountControl, + msDS-User-Account-Control-Computed; for AD LDS it is derived from + the directory attribute msDS-UserPasswordExpired + - PasswordLastSet - A property of type System.DateTime, derived from + the directory attribute: pwdLastSet + - PasswordNeverExpires - A property of type System.Boolean, for AD + LDS it is derived from the directory attributes: + userAccountControl, msDS-User-Account-Control-Computed; for AD LDS + it is derived from the directory attribute: + msDS-UserDontExpirePassword + - PasswordNotRequired - A property of type System.Boolean, for AD DS + it is derived from the directory attributes: userAccountControl, + msDS-User-Account-Control-Computed; for AD LDS it is derived from + the directory attribute: ms-DS-UserPasswordNotRequired + - PrimaryGroup - A property of type System.String, derived from the + directory attributes: primaryGroupID, objectSid. This property is + not supported by AD LDS. + - ServicePrincipalNames - A property of type System.String, derived + from the directory attribute: servicePrincipalName. This property + is not supported by AD LDS. + - TrustedForDelegation - A property of type System.Boolean, derived + from the directory attributes: userAccountControl, + msDS-User-Account-Control-Computed. This property is not supported + by AD LDS. + - TrustedToAuthForDelegation - A property of type System.Boolean, + derived from the directory attributes: userAccountControl, + msDS-User-Account-Control-Computed. This property is not supported + by AD LDS. + - UseDESKeyOnly - A property of type System.Boolean, derived from the + directory attributes: userAccountControl, + msDS-User-Account-Control-Computed. This property is not supported + by AD LDS. + - UserPrincipalName - A property of type System.String, derived from + the directory attribute: userPrincipalName + - ADComputer - Represents a computer and is derived from ADAccount. + An ADComputer may contain the following properties in addition to + those inherited from its parent. + - DNSHostName - A property of type System.String, derived from the + directory attribute: dNSHostName + - IPv4Address - A property of type System.String, derived from the + directory attribute: dNSHostName + - IPv6Address - A property of type System.String, derived from the + directory attribute: dNSHostName + - Location - A property of type System.String, derived from the + directory attribute: location + - ManagedBy - A property of type System.String, derived from the + directory attribute: managedBy + - OperatingSystem - A property of type System.String, derived from + the directory attribute: operatingSystem + - OperatingSystemHotfix - A property of type System.String, derived + from the directory attribute: operatingSystemHotfix + - OperatingSystemServicePack - A property of type System.String, + derived from the directory attribute: operatingSystemServicePack + - OperatingSystemVersion - A property of type System.String, + derived from the directory attribute: operatingSystemVersion + - ServiceAccount - A property of type System.String, derived from + the directory attribute: msDS-HostServiceAccount + - ADServiceAccount - Represents a managed service account; that is, + an Active Directory object of type msDS-ManagerdServiceAccount and + is derived from ADAccount. This class is not supported by AD LDS. + An ADServiceAccount may contain the following properties in + addition to those inherited from its parent. + - HostComputers - A property of type System.String, derived from + the directory attribute: msDS-HostServiceAccountBL + - ADUser - Represents a user (or iNetOrgPerson) and is derived from + ADAccount. An ADUser may contain the following properties in + addition to those inherited from its parent. + - City - A property of type System.String, derived from the + directory attribute: l + - Company - A property of type System.String, derived from the + directory attribute: company + - Country - A property of type System.String, derived from the + directory attribute: c + - Department - A property of type System.String, derived from the + directory attribute: department + - Division - A property of type System.String, derived from the + directory attribute: division + - EmailAddress - A property of type System.String, derived from the + directory attribute: mail + - EmployeeID - A property of type System.String, derived from the + directory attribute: employeeID + - EmployeeNumber - A property of type System.String, derived from + the directory attribute: employeeNumber + - Fax - A property of type System.String, derived from the + directory attribute: facsimileTelephoneNumber + - GivenName - A property of type System.String, derived from the + directory attribute: givenName + - HomeDirectory - A property of type System.String, derived from + the directory attribute: homeDirectory. This property is not + supported by AD LDS. + - HomeDrive - A property of type System.String, derived from the + directory attribute: homeDrive. This property is not supported by + AD LDS. + - HomePhone - A property of type System.String, derived from the + directory attribute: homePhone + - Initials - A property of type System.String, derived from the + directory attribute: initials + - LogonWorkstations - A property of type System.String, derived + from the directory attribute: userWorkstations. This property is + not supported by AD LDS. + - Manager - A property of type System.String, derived from the + directory attribute: manager + - MobilePhone - A property of type System.String, derived from the + directory attribute: mobile + - Office - A property of type System.String, derived from the + directory attribute: physicalDeliveryOfficeName + - OfficePhone - A property of type System.String, derived from the + directory attribute: telephoneNumber + - Organization - A property of type System.String, derived from the + directory attribute: o + - OtherName - A property of type System.String, derived from the + directory attribute: middleName + - POBox - A property of type System.String, derived from the + directory attribute: postOfficeBox + - PostalCode - A property of type System.String, derived from the + directory attribute: postalCode + - ProfilePath - A property of type System.String, derived from the + directory attribute: profilePath. This property is not supported + by AD LDS. + - ScriptPath - A property of type System.String, derived from the + directory attribute: scriptPath. This property is not supported + by AD LDS. + - SmartcardLogonRequired - A property of type System.Boolean, + derived from the directory attributes: userAccountControl, + msDS-User-Account-Control-Computed. This property is not + supported by AD LDS. + - State - A property of type System.String, derived from the + directory attribute: st + - StreetAddress - A property of type System.String, derived from + the directory attribute: streetAddress + - Surname - A property of type System.String, derived from the + directory attribute: sn + - Title - A property of type System.String, derived from the + directory attribute: title + - ADGroup -Represents a group and is derived from ADPrincipal. An + ADGroup may contain the following properties in addition to those + inherited from its parent. + - GroupCategory - A property of type + Microsoft.ActiveDirectory.Management.ADGroupCategory, derived from + the directory attribute: groupType + - GroupScope - A property of type + Microsoft.ActiveDirectory.Management.ADGroupScope, derived from the + directory attribute: groupType + - ManagedBy - A property of type System.String, derived from the + directory attribute: managedBy + - Members - A property of type System.String, derived from the + directory attribute: member + - ADDefaultDomainPasswordPolicy - Represents the domain-wide password policy + of an Active Directory domain and is derived from ADEntity. This class is + not supported by AD LDS. An ADDefaultDomainPasswordPolicy may contain the + following properties in addition to those inherited from its parent. + - ComplexityEnabled - A property of type System.Boolean, derived from the + directory attribute: pwdProperties + - DistinguishedName - A property of type System.String, derived from the + directory attribute: distinguishedName + - LockoutDuration - A property of type System.TimeSpan, derived from the + directory attribute: lockoutDuration + - LockoutObservationWindow - A property of type System.TimeSpan, derived + from the directory attribute: lockoutObservationWindow + - LockoutThreshold - A property of type System.Int32, derived from the + directory attribute: lockoutThreshold + - MaxPasswordAge - A property of type System.TimeSpan, derived from the + directory attribute: maxPwdAge + - MinPasswordAge - A property of type System.TimeSpan, derived from the + directory attribute: minPwdAge + - MinPasswordLength - A property of type System.Int32, derived from the + directory attribute: minPwdLength + - PasswordHistoryCount - A property of type System.Int32, derived from the + directory attribute: pwdHistoryLength + - ReversibleEncryptionEnabled - A property of type System.Boolean, derived + from the directory attribute: pwdProperties + - ADForest - Represents a Active Directory forest in AD DS or a Configuration + Set in AD LDS and is derived from ADEntity. This class is not supported by + AD LDS. An ADForest may contain the following properties in addition to + those inherited from its parent. + - ApplicationPartitions - A property of type System.String, derived from + the directory attribute: ApplicationPartitions + - CrossForestReferences - A property of type System.String, derived from + the directory attribute: CrossForestReferences + - DomainNamingMaster - A property of type System.String, derived from the + directory attribute: DomainNamingMaster + - Domains - A property of type System.String, derived from the directory + attribute: Domains + - ForestMode - A property of type System.Int32, derived from the directory + attribute: msDS-Behavior-Version + - GlobalCatalogs - A property of type System.String, derived from the + directory attribute: GlobalCatalogs + - Name - A property of type System.String, derived from the directory + attribute: name + - PartitionContainerName - A property of type System.String, derived from + the directory attribute: distinguishedName + - RootDomain - A property of type System.String, derived from the directory + attribute: RootDomain + - SchemaMaster - A property of type System.String, derived from the + directory attribute: SchemaMaster + - Sites - A property of type System.String, derived from the directory + attribute: Sites + - SPNSuffixes - A property of type System.String, derived from the + directory attribute: msDS-SPNSuffixes + - UPNSuffixes - A property of type System.String, derived from the + directory attribute: uPNSuffixes + - ADDirectoryServer - Represents a directory server used as either a domain + controller or an AD LDS instance and is derived from ADEntity. An + ADDirectoryServer may contain the following properties in addition to those + inherited from its parent. + - DefaultPartition - A property of type System.String, derived from the + directory attribute: DefaultPartition + - HostName - A property of type System.String, derived from the directory + attribute: HostName + - InvocationId - A property of type System.Guid, derived from the directory + attribute: InvocationId + - IPv4Address - A property of type System.String, derived from the + directory attribute: HostName + - IPv6Address - A property of type System.String, derived from the + directory attribute: HostName + - LdapPort - A property of type System.Int32, derived from the directory + attribute: LdapPort + - Name - A property of type System.String, derived from the directory + attribute: Name + - NTDSSettingsObjectDN - A property of type System.String, derived from the + directory attribute: NTDSSettingsObjectDN + - OperationMasterRoles - A property of type + Microsoft.ActiveDirectory.Management.ADOperationMasterRole, derived from + the directory attribute: OperationMasterRole + - Partitions - A property of type System.String, derived from the directory + attribute: Partitions + - ServerObjectDN - A property of type System.String, derived from the + directory attribute: ServerObjectDN + - ServerObjectGuid - A property of type System.Guid, derived from the + directory attribute: ServerObjectGuid + - Site - A property of type System.String, derived from the directory + attribute: Site + - SslPort - A property of type System.Int32, derived from the directory + attribute: SslPort + - ADDomainController - Represents a domain controller in AD DS and is + derived from ADDirectoryServer. An ADDomainController may contain the + following properties in addition to those inherited from its parent. + - ComputerObjectDN - A property of type System.String, derived from the + directory attribute: ComputerDN + - Domain - A property of type System.String, derived from the directory + attribute: Domain + - Enabled - A property of type System.Boolean, derived from the directory + attribute: Enabled + - Forest - A property of type System.String, derived from the directory + attribute: Forest + - IsGlobalCatalog - A property of type System.Boolean, derived from the + directory attribute: IsGlobalCatalog + - IsReadOnly - A property of type System.Boolean, derived from the + directory attribute: IsReadOnly + - OperatingSystem - A property of type System.String, derived from the + directory attribute: OSName + - OperatingSystemHotfix - A property of type System.String, derived from + the directory attribute: OSHotFix + - OperatingSystemServicePack - A property of type System.String, derived + from the directory attribute: OSServicepack + - OperatingSystemVersion - A property of type System.String, derived from + the directory attribute: OSVersion diff --git a/docset/winserver2016-ps/appx/Get-NonRemovableAppsPolicy.md b/docset/winserver2016-ps/appx/Get-NonRemovableAppsPolicy.md index c485ad124b..536f7912dc 100644 --- a/docset/winserver2016-ps/appx/Get-NonRemovableAppsPolicy.md +++ b/docset/winserver2016-ps/appx/Get-NonRemovableAppsPolicy.md @@ -1,5 +1,6 @@ --- -audiencems.localizationpriority: ITPro +audience: ITPro +ms.localizationpriority: Low description: Use this topic to help prevent the uninstall of specific Windows apps with Windows PowerShell. external help file: Microsoft.Windows.Appx.PackageManager.Commands.dll-help.xml Module Name: Appx diff --git a/docset/winserver2016-ps/appx/Set-NonRemovableAppsPolicy.md b/docset/winserver2016-ps/appx/Set-NonRemovableAppsPolicy.md index 4d5de39176..d671ebb3ee 100644 --- a/docset/winserver2016-ps/appx/Set-NonRemovableAppsPolicy.md +++ b/docset/winserver2016-ps/appx/Set-NonRemovableAppsPolicy.md @@ -1,5 +1,6 @@ --- -audiencems.localizationpriority: ITPro +audience: ITPro +ms.localizationpriority: Low description: Use this topic to help prevent the uninstall of specific Windows apps with Windows PowerShell. external help file: Microsoft.Windows.Appx.PackageManager.Commands.dll-help.xml Module Name: Appx diff --git a/docset/winserver2016-ps/bestpractices/Invoke-BpaModel.md b/docset/winserver2016-ps/bestpractices/Invoke-BpaModel.md index 62ce603109..4a77c4aef0 100644 --- a/docset/winserver2016-ps/bestpractices/Invoke-BpaModel.md +++ b/docset/winserver2016-ps/bestpractices/Invoke-BpaModel.md @@ -36,7 +36,6 @@ If a model is specified in the cmdlet after the BPA scan has been performed, the This cmdlet cannot be canceled after it has been started. Single-node XML is not supported by the BPA model schema. -For more information about what is supported by the BPA model schema, see the [Microsoft Baseline Configuration Analyzer Model Authoring Guide](https://www.microsoft.com/download/details.aspx?id=16475) on the [Microsoft Download Center](https://www.microsoft.com/download/details.aspx?id=16475). ## EXAMPLES diff --git a/docset/winserver2016-ps/hyper-v/Get-VMNetworkAdapter.md b/docset/winserver2016-ps/hyper-v/Get-VMNetworkAdapter.md index 8c22b96d92..9ac6fab263 100644 --- a/docset/winserver2016-ps/hyper-v/Get-VMNetworkAdapter.md +++ b/docset/winserver2016-ps/hyper-v/Get-VMNetworkAdapter.md @@ -203,7 +203,7 @@ Accept wildcard characters: False ### -VM Specifies the virtual machine whose virtual network adapters are to be retrieved. -. The asterisk, "*", is the wildcard. +The asterisk, "*", is the wildcard. If it is specified the cmdlet returns virtual network adapters from every virtual machine in the system. ```yaml diff --git a/docset/winserver2019-ps/activedirectory/About/About.md b/docset/winserver2019-ps/activedirectory/About/About.md new file mode 100644 index 0000000000..449df28850 --- /dev/null +++ b/docset/winserver2019-ps/activedirectory/About/About.md @@ -0,0 +1,26 @@ +--- +description: About articles for the ActiveDirectory module. +Help Version: 3.1.0.0 +Locale: en-US +ms.date: 07/03/2024 +title: About articles +--- +# About topics + +## Description + +About topics cover a range of concepts about PowerShell. + +## About Topics + +### [about_ActiveDirectory](about_ActiveDirectory.md) +The Active Directory module is a command line interface for managing Active Directory. + +### [about_ActiveDirectory_Filter](about_ActiveDirectory_Filter.md) +Describes the syntax and behavior of the search filter supported by the Active Directory module for Windows PowerShell. + +### [about_ActiveDirectory_Identity](about_ActiveDirectory_Identity.md) +The Active Directory module for Windows PowerShell objects have a range of identifying attributes that are used for search and retrieval. + +### [about_ActiveDirectory_ObjectModel](about_ActiveDirectory_ObjectModel.md) +Describes the object model of the Active Directory module for Windows PowerShell. diff --git a/docset/winserver2019-ps/activedirectory/About/about_ActiveDirectory.md b/docset/winserver2019-ps/activedirectory/About/about_ActiveDirectory.md new file mode 100644 index 0000000000..1b7183dcd2 --- /dev/null +++ b/docset/winserver2019-ps/activedirectory/About/about_ActiveDirectory.md @@ -0,0 +1,81 @@ +--- +title: about_ActiveDirectory +ms.date: 04/22/2013 +description: The Active Directory module is a command line interface for managing Active Directory. +Locale: en-US +schema: 2.0.0 +--- + +# about_ActiveDirectory + +## SHORT DESCRIPTION + +The Active Directory module is a command line interface for managing Active +Directory. + +## LONG DESCRIPTION + +The Active Directory module for Windows PowerShell is for IT Professionals who +are administering and interfacing with Active Directory. The Active Directory +module provides an efficient way to complete many administrative, +configuration, and diagnostic tasks across Active Directory Domain Services (AD +DS) and Active Directory Lightweight Directory Services (AD LDS) instances in +their environments. The Active Directory module includes a set of Windows +PowerShell cmdlets and a provider. The provider exposes the Active Directory +database through a hierarchical navigation system, which is very similar to the +file system. As with drives in a file system, such as C:, you can connect +Windows PowerShell drives to Active Directory domains and AD LDS, as well as +Active Directory snapshots. + +### Coverage of Active Directory Module Cmdlets + +Create, Read, Update, and Delete actions are supported for Active Directory +objects by cmdlets such as `New-ADUser`, `Get-ADOrganizationalUnit`, +`Set-ADComputer`, and `Remove-ADUser`. + +Account and Password Policy Management are supported by cmdlets such as +`Enable-ADAccount`, `Unlock-ADAccount`, `New-ADServiceAccount`, +`Set-ADAccountControl`, and `Remove-ADFineGrainedPasswordPolicy`. + +Domain and Forest Management is supported by cmdlets such as `Get-ADForest`, +`Set-ADForest`, `Set-ADForestMode`, `Enable-ADOptionalFeature`, +`Get-ADDomainController`, and `Get-ADDomain`. + +### Listing the Active Directory Module Cmdlets + +To get a list of all of the Active Directory module cmdlets, run + +```powershell +Get-Command -Module ActiveDirectory +``` + +### Getting Started + +Getting started with the Active Directory module for Windows PowerShell is as +easy as clicking the following shortcut: + +Run the following command in any Windows PowerShell prompt to import the Active +Directory module: + +```powershell +Import-Module ActiveDirectory +``` + +### Overview and Conceptual Topics + +The first two of these topics offer a high level overview of the Active +Directory module and the Active Directory Provider. + +- For a brief introduction to the Active Directory provider for Windows + PowerShell, see [ActiveDirectory](/powershell/module/activedirectory). +- The following topics are conceptual support topics for the Active Directory + module cmdlets. + - For an introduction to the **Identity** parameter, which is used by the + Active Directory module cmdlets to identify objects in the directory, see + [about_ActiveDirectory_Identity](about_ActiveDirectory_Identity.md). + - For an introduction to the **Filter** parameter which is used by Active + Directory module cmdlets to search for objects in the directory, see + [about_ActiveDirectory_Filter](about_ActiveDirectory_Filter.md). + - For an introduction to the .NET Framework-based object model implemented by + the Active Directory module, see + [about_ActiveDirectory_ObjectModel](about_ActiveDirectory_ObjectModel.md). diff --git a/docset/winserver2019-ps/activedirectory/About/about_ActiveDirectory_Filter.md b/docset/winserver2019-ps/activedirectory/About/about_ActiveDirectory_Filter.md new file mode 100644 index 0000000000..23a83c0a0a --- /dev/null +++ b/docset/winserver2019-ps/activedirectory/About/about_ActiveDirectory_Filter.md @@ -0,0 +1,351 @@ +--- +title: about_ActiveDirectory_Filter +ms.date: 04/22/2013 +description: Describes the syntax and behavior of the search filter supported by the Active Directory module for Windows PowerShell. +Locale: en-US +schema: 2.0.0 +--- + +# about_ActiveDirectory_Filter + +## SHORT DESCRIPTION + +Describes the syntax and behavior of the search filter supported by the Active +Directory module for Windows PowerShell. + +## LONG DESCRIPTION + +Most get-AD* Active Directory module cmdlets use the Filter parameter to search +for objects. The Filter parameter has been implemented to replace the function +of the LDAP Filter and adds support for PowerShell variables, rich data types, +improved error checking and an Active Directory extended form of the PowerShell +Expression Language. + + +- Support for LDAP Filter Syntax + + The LDAP filter syntax is supported through the **LDAPFilter** parameter. You + will find LDAP filter examples along with the new Active Directory module + filter examples in the Filter Examples section of this topic. + + +- Search Breadth and Depth + + The breadth and depth of your filter-driven search can be modified by two + Active Directory module cmdlet parameters: **SearchBase** and **SearchScope**. + + When within the context of the Active Directory provider, if the + **Searchbase** parameter is not specified, **SearchBase** will default to the + current path. When not running under the Active Directory provider, the + **SearchBase** will default to the server's **DefaultNamingContext**. + + The **SearchScope** parameter defaults to the value `Subtree`, of the + enumerated type **ADSearchScope**. + + For more information, see the **SearchBase** and **SearchScope** parameter + descriptions on any `Get-AD*` cmdlet. + +- Search Result Behavior + + The behavior of the Active Directory module when returning results of a + search is modified by two cmdlet parameters: **ResultPageSize** and + **ResultSetSize**. + + **ResultSetSize** controls the maximum number of returned objects. + + **ResultPageSize** specifies the maximum number of objects for each returned + page of information. + + See the **ResultPageSize** and **ResultSetSize** parameter descriptions on + any `Get-AD*` cmdlet for more information. + + +- Timeout Behavior + + The following statements specify timeout conditions within the Active + Directory module and describe what can be done about a timeout them. + + The default Active Directory module timeout for all operations is 2 + minutes. + + For search operation, the Active Directory module uses paging control + with a 2-minute timeout for each page search. + + > [!NOTE] + > Because a search may involve multiple server page requests the overall + > search time may exceed 2 minutes. + + A **TimeoutException** error indicates that a timeout has occurred. + + For a search operation, you can choose to use a smaller page size, set with + the **ResultPageSize** parameter, if you are getting a **TimeoutException** + error. + + If after trying these changes you are still getting a **TimeoutException** + error, consider optimizing your filter using the guidance in the + Optimizing Filters section of this topic. + + +- Optimizing Filters + + You can enhance the search filter behavior by using these guidelines. + + - Avoid using the **Recursive** parameter as it intensifies resource usage of + the search operation. + - Avoid using bitwise AND operators and bitwise OR operators. For more + information, see the Supported Operators section of this topic. + - Avoid using the logical NOT operator. + - Break down your search into multiple queries with narrower conditions. + + For a full description of filter syntax and usage, see the Filter Syntax + section of this topic. + + +## Filter Examples + +The following section shows many examples of filter use in common queries. + +### Example 1 - Get all entries: + +- LDAP Filter Equivalent: `(objectClass=*)` + +```powershell +Get-ADObject -Filter 'ObjectClass -like "*"' +``` + +### Example 2 - Get entries containing "bob" somewhere in the common name + +- LDAP Filter Equivalent: `(cn=*bob*)` + +```powershell +Get-ADObject -Filter 'CN -like "*bob*"' +``` + +### Example 3 - Get entries with a bad password count greater than five + +- LDAP Filter Equivalent: `(&(!badpwdcount<=5)(badpwdcount=*))` + +```powershell +Get-ADUser -Filter 'badpwdcount -ge 5' +``` + +### Example 4 - Get all users with an e-mail attribute + +- LDAP Filter Equivalent: `(&(objectClass=user)(email=*))` + +```powershell +Get-ADUser -filter 'email -like "*"' +``` + +-or- + +```powershell +Get-ADObject -filter 'email -like "*" -and ObjectClass -eq "user"' +``` + +### Example 5 - Get all user entries with an e-mail attribute and a surname equal to "smith": + +- LDAP Filter Equivalent: `(&(sn=smith)(objectClass=user)(email=*))` + +```powershell +Get-ADUser -Filter 'Email -like "*" -and SurName -eq "smith"' +``` + +-or- + +```powershell +Get-ADUser -Filter 'Email -like "*" -and sn -eq "smith"' +``` + + +### Example 6 - Get all user entries with a common name that starts with "andy" and users with a common name of "steve" or "margaret" + +- LDAP Filter Equivalent: `(&(objectClass=user) | (cn=andy*)(cn=steve)(cn=margaret))` + +```powershell +Get-ADUser -Filter 'CN -like "andy*" -or CN -eq "steve" -or CN -eq "margaret"' +``` + + +This example demonstrates a more complex logic and the use of precedence +control via parenthesis. + +```powershell +Get-ADObject -Filter 'objectClass -eq "user" -and (CN -like "andy*" -or CN -eq "steve" -or CN -eq "margaret")' +``` + +### Example 7 - Get all entries without an e-mail attribute + +- LDAP Filter Equivalent: `(!(email=*))` + +```powershell +Get-ADUser -Filter '-not Email -like "*"' +``` + +-or- + +```powershell +Get-ADUser -Filter 'Email -notlike "*"' +``` + +### Example 8 - Get all users who did not logon since January 1, 2007 + +- LDAP Filter Equivalent: `(&(lastlogon<=X)(objectClass=user))` where X is + number of 100-nanosecond slices since Jan 1st 1601 + +```powershell +$date = new-object System.DateTime -ArgumentList @(2007,1,1,0,0,0) +Get-ADUser -Filter '-not LastLogon -le $date' +``` + +### Example 9 - Get all users who have logged on in the last 5 days + +- LDAP Filter Equivalent: + + ``` + (&(lastLogon>=128812906535515110) + (objectClass=user)(!(objectClass=computer))) + ``` + +```powershell +$date = (get-date) - (new-timespan -days 5) +Get-ADUser -Filter 'lastLogon -gt $date' +``` + +### Example 10 - Search for group objects that have the ADS_GROUP_TYPE_SECURITY_ENABLED flag set + +- LDAP Filter Equivalent: + `(&(objectCategory=group)(groupType:1.2.840.113556.1.4.803:=2147483648))` + +The following example query string searches for group objects that have the +ADS_GROUP_TYPE_SECURITY_ENABLED flag set. Be aware that the decimal value of +ADS_GROUP_TYPE_SECURITY_ENABLED (0x80000000 = 2147483648) is used for the +comparison value. + +```powershell +Get-ADGroup -filter 'groupType -band 0x80000000' +``` + +### Example 11 - Search the ancestry of an object + +- LDAP Filter Equivalent: + `(memberof:1.2.840.113556.1.4.1941:=(cn=Group1,OU=groupsOU,DC=x)))` + +The LDAP_MATCHING_RULE_IN_CHAIN is a matching rule OID that is designed to +provide a method to look up the ancestry of an object. Many applications using +Active Directory and AD LDS usually work with hierarchical data, which is +ordered by parent-child relationships. Previously, applications performed +transitive group expansion to figure out group membership, which used a lot of +network bandwidth. Applications made multiple round-trips to figure out if an +object fell "in the chain" if a link were traversed through to the end. + +An example of such a query is one designed to check if a user, "user1" is a +member of group "group1". "user1" may not be a direct member of group1. It +could be a member of some other group, which is a member of "group1". + +You would set the base to the user DN and the scope to base, and use the query: + +```powershell +Get-ADUser -Filter 'memberOf -RecursiveMatch "CN=Administrators, CN=Builtin,DC=Fabrikam,DC=com"' -SearchBase "CN=Administrator,CN=Users,DC=Fabrikam,DC=com" +``` + +## Filter Syntax + +The following syntax descriptions use Backus-Naur form to show the PowerShell +Expression Language for the Filter parameter. + +```Syntax + ::= "{" "}" + + ::= | + | + + + ::= | + "(" ")" + + ::= "-eq" | "-le" | "-ge" | "-ne" | "-lt" | "-gt" | + "-approx" | "-bor" | "-band" | "-recursivematch" | "-like" | + "-notlike" + + ::= "-and" | "-or" + + ::= "-not" + + ::= | + +::= < this value will be compared to the object data for + attribute using the specified filter operator +``` + + +## Supported Operators + +The following table shows frequently used search filter operators. + +| Operator | Description | LDAP Equivalent | +| ----------------- | -------------------------------------- | -------------------------- | +| `-eq` | Equal to. Wildcards not supported. | = | +| `-ne` | Not equal to. Wildcards not supported. | !x = y | +| `-approx` | Approximately equal to | ~= | +| `-le` | Lexicographically less than | <= | +| | or equal to | | +| `-lt` | Lexicographically less than | !x >= y | +| `-ge` | Lexicographically greater | >= | +| | than or equal to | | +| `-gt` | Lexicographically greater than | !x <= y | +| | | | +| `-and` | AND | & | +| `-or` | OR | | +| `-not` | NOT | ! | +| `-bor` | Bitwise OR | :1.2.840.113556.1.4.804:= | +| `-band` | Bitwise AND | :1.2.840.113556.1.4.803:= | +| `-recursivematch` | Use LDAP_MATCHING_RULE_IN_CHAIN | :1.2.840.113556.1.4.1941:= | +| `-like` | Similar to `-eq` and supports | = | +| | wildcard comparison. The only | | +| | wildcard character supported is: `*` | | +| `-notlike` | Not like. Supports wild | !x = y | +| | card comparison. | | + +> [!NOTE] +> PowerShell wildcards, other than "*", such as "?" are not supported by the +> **Filter** parameter syntax. + +### Operator Precedence + +The following listing shows the precedence of operators for filters from +highest to lowest. + +- Highest precedence: `-eq`, `-ge`, `-le`, `-approx`, `-band`, `-bor`, + `-recursivematch`, `-ne`, `-like`, `-not`, `-and` +- Lowest precedence: `-or` + +### Special Characters + +The following escape sequence should be used for specifying special characters +in AD Filter STRING data, that is, data enclosed in double or single quotes. + +| ASCII Character | Escape sequence substitute | +| --------------- | --------------------------------------------------- | +| `"` | `` `" `` (This escape sequence is only required if | +| | STRING data is enclosed in double quotes.) | +| `'` | `''` (This escape sequence is only required if | +| | STRING data is enclosed in single quotes.) | +| NUL | `\00` (This is a standard LDAP escape sequence.) | +| `\` | `\5c` (This is a standard LDAP escape sequence.) | + +### LDAP Special Characters + +ADFilter parser will automatically convert all the below characters found in +STRING data, that is data enclosed in " " or ' ' to their LDAP escape sequence. +End users need not know about these LDAP escape sequence. + +| ASCII Character | Escape sequence substitute | +| --------------- | ----------------------------------------------- | +| `*` | `\2a` (Character `*` will only be converted in | +| | -eq and -ne comparisons Users should use | +| | -like and -notlike operators for wildcard | +| | comparison.) | +| `(` | `\28` | +| `)` | `\29` | +| `/` | `\2f` | diff --git a/docset/winserver2019-ps/activedirectory/About/about_ActiveDirectory_Identity.md b/docset/winserver2019-ps/activedirectory/About/about_ActiveDirectory_Identity.md new file mode 100644 index 0000000000..c007277b19 --- /dev/null +++ b/docset/winserver2019-ps/activedirectory/About/about_ActiveDirectory_Identity.md @@ -0,0 +1,196 @@ +--- +title: about_ActiveDirectory_Identity +ms.date: 04/22/2013 +description: This article lists the identifying attributes that are used for search and retrieval supported by the Active Directory module for Windows PowerShell. +Locale: en-US +schema: 2.0.0 +--- + +# about_ActiveDirectory_Identity + +## SHORT DESCRIPTION + +The Active Directory module for Windows PowerShell objects have a range of +identifying attributes that are used for search and retrieval. + +## LONG DESCRIPTION + +In order to identify the objects in Active Directory, each object has +attributes that can be used as identifiers. In the Active Directory module, the +value of the identity of an object can be passed using the Identity parameter. +Each object type has its own set of possible types and values for use by the +Identity parameter. See the detailed description of the Identity parameter of +the given cmdlet for more information about its usage. + +When searching with the Active Directory module cmdlets, the value of the +Identity parameter, along with the values of the Server and Partition +parameters, is used to uniquely identify a single object. The Server parameter +is used to locate which server to connect with. The Partition parameter further +narrows the search to a specific partition. The Identity parameter then +resolves to a single unique object in the partition. + +Note that using the Security Accounts Manager (SAM) Account Name +(**sAMAccountName**) when targeting a global catalog port, you will not find a +user in a different domain if you are using the Identity parameter + +If more than one object is found using identity resolution, the Active +Directory module throws an error. + +For more information about the Server and Partition parameters, see the help +topics for the individual cmdlets where they are used, such as `Get-ADUser`, by +typing: + +```powershell +Get-Help Get-ADUser +``` + +### Objects and Identities + +Each object has a list of attributes that can be used as an identity for that +object. Additionally, if the object inherits from another object, then the +parent object's identities can also be used as the child object's identities. +For more information on the Active Directory object hierarchy, see +[about_ActiveDirectory_ObjectModel](about_ActiveDirectory_ObjectModel.md). + +> [!NOTE] +> For Active Directory Provider cmdlets, only an object's 'Distinguished Name' +> or 'Relative Distinguished Name' can be used as the identity. For a list of +> Active Directory Provider cmdlets, see ActiveDirectory. + +### Identity Attributes + +The following is a list of identity attributes by object type. + +- ADAccount + - Distinguished Name + - GUID (objectGUID) + - Security Identifier (objectSid) + - SAM Account Name (sAMAccountName) + +- ADComputer + - Distinguished Name + - GUID (objectGUID) + - Security Identifier (objectSid) + - Security Accounts Manager Account Name (sAMAccountName) + +- ADDirectoryServer + - Name of the server object (name) + - For AD LDS instances the syntax of a name is `$` + - For other Active Directory instances, use the value of the name property. + - Distinguished Name of the NTDS Settings object + - Distinguished Name of the server object that represents the directory + server. + - GUID (objectGUID) of server object under the configuration partition. + - GUID (objectGUID) of NTDS settings object under the configuration partition + +- ADDomain + - Distinguished Name + - GUID + - Security Identifier + - DNS domain name + - NetBIOS domain name + +- ADDomainController + - GUID (objectGUID) + - IPV4Address + - Global IPV6Address + - DNS Host Name (dNSHostName) + - Name of the server object + - Distinguished Name of the NTDS Settings object + - Distinguished Name of the server object that represents the domain controller + - GUID of NTDS settings object under the configuration partition + - GUID of server object under the configuration partition + - Distinguished Name of the computer object that represents the domain controller. + +- ADFineGrainedPasswordPolicy + - Distinguished Name + - GUID (objectGUID) + - Name (name) + +- ADForest + - Fully qualified domain name + - DNS host name + - NetBIOS name + +- ADGroup + - Distinguished Name + - GUID (objectGUID) + - Security Identifier (objectSid) + - Security Accounts Manager (SAM) Account Name (sAMAccountName) + +- ADObject + - Distinguished Name + - GUID (objectGUID) + +- ADOptionalFeature + - Distinguished Name + - Name (name) + - Feature GUID (featureGUID) + - GUID (objectGUID) + +- ADOrganizationalUnit + - Distinguished Name + - GUID (objectGUID) + +- ADPrincipal + - Distinguished Name + - GUID (objectGUID) + - Security Identifier (objectSid) + - SAM Account Name (sAMAccountName) + +- ADServiceAccount + - Distinguished Name + - GUID (objectGUID) + - Security Identifier (objectSid) + - SAM Account Name (sAMAccountName) + +- ADUser + - Distinguished Name + - GUID (objectGUID) + - Security Identifier (objectSid) + - SAM User Name (sAMUserName) + + +### Identities Formats + +Active Directory module objects have a range of identity attributes. Below is a +list of these, their types and formats. + +- Distinguished Name + - Example: CN=SaraDavis,CN=Europe,CN=Users, DC=corp,DC=contoso,DC=com + +- DNS domain name + - Example: redmond.corp.contoso.com + +- DNS Host Name (dNSHostName) + - Example: corp-DC01.corp.contoso.com + +- Feature GUID (featureGUID) + - Example: 599c3d2e-f72d-4d20-8a88-030d99495f20 + +- Fully qualified domain name + - Example: corp.contoso.com + +- Global IPV6Address + - Example: 2001:4898:0:fff:200:5efe:157.59.132.61 + +- GUID (objectGUID) + - Example: 599c3d2e-f72d-4d20-8a88-030d99495f20 + +- IPV4Address + - Example:157.59.132.61 + +- NetBIOS domain name + - Example: redmond + +- Name of the server object + - Example: corp-DC01$ + +- SAM Account Name (sAMAccountName) + - Example: saradavisreports + +- Security Identifier (objectSid) + - Example: S-1-5-21-3165297888-301567370-576410423-1103 + +- Name + - Example: Recycle Bin Feature diff --git a/docset/winserver2019-ps/activedirectory/About/about_ActiveDirectory_ObjectModel.md b/docset/winserver2019-ps/activedirectory/About/about_ActiveDirectory_ObjectModel.md new file mode 100644 index 0000000000..8535a97464 --- /dev/null +++ b/docset/winserver2019-ps/activedirectory/About/about_ActiveDirectory_ObjectModel.md @@ -0,0 +1,595 @@ +--- +title: about_ActiveDirectory_ObjectModel +ms.date: 04/22/2013 +description: Describes the object model of the Active Directory module for Windows PowerShell. +Locale: en-US +schema: 2.0.0 +--- + +# about_ActiveDirectory_ObjectModel + +## SHORT DESCRIPTION +Describes the object model of the Active Directory module for Windows +PowerShell. + +## LONG DESCRIPTION + +This topic explains the Active Directory module classes and their properties +used to model actual Active Directory attributes. It also outlines the class +hierarchy constructed from its Active Directory counterpart. The object model +establishes a data foundation for all the operations supported by Active +Directory module cmdlets. + +### Class Hierarchy + +The following list shows the class hierarchy defined in the Active Directory +module object model, with class inheritance implied by indentation. This +inheritance model allows for Active Directory cmdlets to accept a range of +object types as input. This means, for example, that the cmdlet +Get-ADPrincipalGroupMembership can accept as input any of the following +objects: ADGroup, ADAccount, ADComputer, ADServiceAccount or ADUser. This works +because of the inheritance model and guarantees that an ADUser object has all +of the properties of an ADPrincipal object. + +``` +ADEntity + ADRootDSE + ADObject + ADFineGrainedPasswordPolicy + ADOptionalFeature + ADOrganizationalUnit + ADPartition + ADDomain + ADPrincipal + ADAccount + ADComputer + ADServiceAccount + ADUser + ADGroup + ADDefaultDomainPasswordPolicy + ADForest + ADDirectoryServer + ADDomainController +``` + +### Active Directory Module Classes + +The following listing shows every Active Directory module class from the class +hierarchy listing. Each class defines a set of properties, some of which are +LDAP attributes that are retrieved by default and some are new properties +created specifically for the Active Directory module. These new properties are +derived from one or more LDAP attributes as outlined in the class listings. + + +- ADEntity - The base level class from which all other classes are derived. + - ADRootDSE - Represents the rootDSE and is derived from ADEntity. An + ADRootDSE may contain the following properties in addition to those + inherited from its parent. + - ConfigurationNamingContext - A property of type System.String, derived + from the directory attribute ConfigurationNamingContext + - CurrentTime - A property of type System.DateTime, derived from the + directory attribute CurrentTime + - DefaultNamingContext - A property of type System.String, derived from the + directory attribute DefaultNamingContext + - DnsHostName - A property of type System.String, derived from the + directory attribute DnsHostName + - DomainControllerFunctionality - A property of type + ADDomainControllerMode, derived from the directory attribute + DomainControllerFunctionality + - DomainFunctionality - A property of type ADDomainMode, derived from the + directory attribute DomainFunctionality + - DsServiceName - A property of type System.String, derived from the + directory attribute DsServiceName + - ForestFunctionality - A property of type ADForestMode, derived from the + directory attribute ForestFunctionality + - GlobalCatalogReady - A property of type System.Boolean, derived from the + directory attribute GlobalCatalogReady + - HighestCommittedUSN - A property of type System.Long, derived from the + directory attribute HighestCommittedUSN + - LdapServiceName - A property of type System.String, derived from the + directory attribute LdapServiceName + - NamingContexts - A property of type System.String, derived from the + directory attribute NamingContexts + - RootDomainNamingContext - A property of type System.String, derived from + the directory attribute RootDomainNamingContext + - SchemaNamingContext - A property of type System.String, derived from the + directory attribute SchemaNamingContext + - ServerName - A property of type System.String, derived from the directory + attribute ServerName + - SubschemaSubentry - A property of type ADObject, derived from the + directory attribute SubschemaSubentry + - SupportedCapabilities - A property of type ADObjectIdentifier, derived + from the directory attribute SupportedCapabilities + - SupportedControl - A property of type ADObjectIdentifier, derived from + the directory attribute SupportedControl + - SupportedLDAPPolicies - A property of type System.String, derived from + the directory attribute SupportedLDAPPolicies + - SupportedLDAPVersion - A property of type System.Int, derived from the + directory attribute SupportedLDAPVersion + - SupportedRootDSEOperations - A property of type + ADPropertyValueCollection, derived from the directory attribute + SupportedRootDSEOperations + - SupportedSASLMechanisms - A property of type System.String, derived from + the directory attribute SupportedSASLMechanisms + - Syncronized - A property of type System.Boolean, derived from the + directory attribute IsSynchronized. + - ADObject - Represents any object in Active Directory and is derived from + ADEntity. An ADObject may contain the following properties in addition to + those inherited from its parent. + - CanonicalName - A property of type System.String, derived from the + directory attribute: canonicalName + - CN - A property of type System.String, derived from the directory + attribute: cn + - Created - A property of type System.DateTime, derived from the directory + attribute: createTimeStamp + - Deleted - A property of type System.Boolean, derived from the directory + attribute: isDeleted + - Description - A property of type System.String, derived from the + directory attribute: description + - DisplayName - A property of type System.String, derived from the + directory attribute: displayName + - DistinguishedName - A property of type System.String, derived from the + directory attribute: distinguishedName + - LastKnownParent - A property of type System.String, derived from the + directory attribute: lastKnownParent + - Modified - A property of type System.DateTime, derived from the directory + attribute: modifyTimeStamp + - Name - A property of type System.String, derived from the directory + attribute: name + - ObjectCategory - A property of type System.String, derived from the + directory attribute: objectCategory + - ObjectClass - A property of type System.String, derived from the + directory attribute: objectClass + - ObjectGUID - A property of type System.Guid, derived from the directory + attribute: objectGUID + - ProtectedFromAccidentalDeletion - A property of type System.Boolean, + derived from the directory attributes: nTSecurityDescriptor, + sdRightsEffective, instanceType, isDeleted + - ADFineGrainedPasswordPolicy Represents a fine grained password policy + object; that is, an AD object of type msDS-PasswordSettings in AD DS and + is derived from ADObject. This class is not supported by AD LDS. An + ADFineGrainedPasswordPolicy may contain the following properties in + addition to those inherited from its parent. + - AppliesTo - A property of type System.String, derived from the + directory attribute: msDS-PSOAppliesTo + - ComplexityEnabled - A property of type System.Boolean, derived from the + directory attribute: msDS-PasswordComplexityEnabled + - LockoutDuration - A property of type System.TimeSpan, derived from the + directory attribute: msDS-LockoutDuration + - LockoutObservationWindow - A property of type System.TimeSpan, derived + from the directory attribute: msDS-LockoutObservationWindow + - LockoutThreshold - A property of type System.Int32, derived from the + directory attribute: msDS-LockoutThreshold + - MaxPasswordAge - A property of type System.TimeSpan, derived from the + directory attribute: msDS-MaximumPasswordAge + - MinPasswordAge - A property of type System.TimeSpan, derived from the + directory attribute: msDS-MinimumPasswordAge + - MinPasswordLength - A property of type System.Int32, derived from the + directory attribute: msDS-MinimumPasswordLength + - PasswordHistoryCount - A property of type System.Int32, derived from + the directory attribute: msDS-PasswordHistoryLength + - Precedence - A property of type System.Int32, derived from the + directory attribute: msDS-PasswordSettingsPrecedence + - ReversibleEncryptionEnabled - A property of type System.Boolean, + derived from the directory attribute: + msDS-PasswordReversibleEncryptionEnabled + - ADOptionalFeature Represents an optional feature, an Active Directory + object of type msDS-OptionalFeature, and is derived from ADObject. An + ADOptionalFeaturemay contain the following properties in addition to + those inherited from its parent. + - EnabledScopes - A property of type System.String, derived from the + directory attribute: msDS-EnabledFeatureBL + - FeatureGUID - A property of type System.Guid, derived from the + directory attribute: msDS-OptionalFeatureGUID + - FeatureScope - A property of type System.Int32, derived from the + directory attribute: msDS-OptionalFeatureFlags + - IsDisableable - A property of type System.Boolean, derived from the + directory attribute: msDS-OptionalFeatureFlags + - RequiredDomainMode - A property of type + Microsoft.ActiveDirectory.Management.ADDomainMode, derived from the + directory attribute: msDS-RequiredDomainBehaviorVersion + - RequiredForestMode - A property of type + Microsoft.ActiveDirectory.Management.ADForestMode, derived from the + directory attribute: msDS-RequiredForestBehaviorVersion + - ADOrganizationalUnit Represents an organizationalUnit (OU) object and is + derived from ADObject. An ADOrganizationalUnit may contain the following + properties in addition to those inherited from its parent. + - City - A property of type System.String, derived from the directory + attribute: l + - Country - A property of type System.String, derived from the directory + attribute: c + - LinkedGroupPolicyObjects - A property of type System.String, derived + from the directory attribute: gpLink. This property is not supported on + AD LDS. + - ManagedBy - A property of type System.String, derived from the + directory attribute: managedBy + - PostalCode - A property of type System.String, derived from the + directory attribute: postalCode + - State - A property of type System.String, derived from the directory + attribute: st + - StreetAddress - A property of type System.String, derived from the + directory attribute: street + - ADPartition - Represents a naming context, Configuration, Schema, Domain + or Application Partition(ND NC) and is derived from ADObject. This class + is not supported by AD LDS. An ADPartition may contain the following + properties in addition to those inherited from its parent. + - DeletedObjectsContainer - A property of type System.String, derived + from the directory attribute: DeletedObjectsContainer + - DNSRoot - A property of type System.String, derived from the directory + attribute: DNSRoot + - LostAndFoundContainer - A property of type System.String, derived from + the directory attribute: LostAndFoundContainer + - QuotasContainer - A property of type System.String, derived from the + directory attribute: QuotasContainer + - ReadOnlyReplicaDirectoryServers - A property of type System.String, + derived from the directory attribute: ReadOnlyReplicaDirectoryServers + - ReplicaDirectoryServers - A property of type System.String, derived + from the directory attribute: ReplicaDirectoryServers + - SubordinateReferences - A property of type System.String, derived from + the directory attribute: SubordinateReferences + - ADDomain - Represents a domain in AD DS or an instance in AD LDS; for + example, an Active Directory object of type domainDNS and is derived + from ADPartition. This class is not supported by AD LDS. An ADDomain + may contain the following properties in addition to those inherited + from its parent. + - AllowedDNSSuffixes - A property of type System.String, derived from + the directory attribute: msDS-AllowedDNSSuffixes + - ChildDomains - A property of type System.String, derived from the + directory attribute: ChildDomains + - ComputersContainer - A property of type System.String, derived from + the directory attribute: ComputersContainer + - DomainControllersContainer - A property of type System.String, + derived from the directory attribute: DomainControllersContainer + - DomainMode - A property of type System.Int32, derived from the + directory attribute: msDS-Behavior-Version + - DomainSID - A property of type + System.Security.Principal.SecurityIdentifier, derived from the + directory attribute: objectSid + - ForeignSecurityPrincipalsContainer - A property of type + System.String, derived from the directory attribute: + ForeignSecurityPrincipalsContainer + - Forest - A property of type System.String, derived from the directory + attribute: Forest + - InfrastructureMaster - A property of type System.String, derived from + the directory attribute: InfrastructureMaster + - LastLogonReplicationInterval - A property of type System.TimeSpan, + derived from the directory attribute: msDS-LogonTimeSyncInterval + - LinkedGroupPolicyObjects - A property of type System.String, derived + from the directory attribute: LinkedGroupPolicyObjects + - ManagedBy - A property of type System.String, derived from the + directory attribute: managedBy + - NetBIOSName - A property of type System.String, derived from the + directory attribute: NetBIOSName + - ParentDomain - A property of type System.String, derived from the + directory attribute: ParentDomain + - PDCEmulator - A property of type System.String, derived from the + directory attribute: PDCEmulator + - RIDMaster - A property of type System.String, derived from the + directory attribute: RIDMaster + - SystemsContainer - A property of type System.String, derived from the + directory attribute: SystemsContainer + - UsersContainer - A property of type System.String, derived from the + directory attribute: UsersContainer + - ADPrincipal - Represents a security principal, which is an Active + Directory object of type user, computer, group or iNetOrgPerson and is + derived from ADObject. An ADPrincipal may contain the following + properties in addition to those inherited from its parent. + - HomePage - A property of type System.String, derived from the + directory attribute: wWWHomePage + - MemberOf - A property of type System.String, derived from the + directory attribute: memberOf + - SamAccountName - A property of type System.String, derived from the + directory attribute: sAMAccountName. This property is not supported + for AD LDS. + - SID - A property of type + System.Security.Principal.SecurityIdentifier, derived from the + directory attribute: objectSid + - SIDHistory - A property of type + System.Security.Principal.SecurityIdentifier, derived from the + directory attribute: sIDHistory. This property is not supported for + AD LDS. + - ADAccount - Represents a security account; that is, an Active + Directory object of type user, computer or iNetOrgPerson and is + derived from ADPrincipal. An ADAccount may contain the following + properties in addition to those inherited from its parent. + - AccountExpirationDate - A property of type System.DateTime, derived + from the directory attribute: accountExpires + - AccountLockoutTime - A property of type System.DateTime, derived + from the directory attribute: lockoutTime + - AccountNotDelegated - A property of type System.Boolean, derived + from the directory attributes: userAccountControl, + msDS-User-Account-Control-Computed. This property is not supported + by AD LDS. + - AllowReversiblePasswordEncryption - A property of type + System.Boolean, for AD DS it is derived from the directory + attribute: userAccountControl; for AD LDS it is derived from the + directory attribute: ms-DS-UserEncryptedTextPasswordAllowed + - BadLogonCount - A property of type System.Int32, derived from the + directory attribute: badPwdCount + - CannotChangePassword - A property of type System.Boolean, derived + from the directory attribute: nTSecurityDescriptor + - Certificates - A property of type + System.Security.Cryptography.X509Certificates.X509Certificate, + derived from the directory attribute: userCertificate + - DoesNotRequirePreAuth - A property of type System.Boolean, derived + from the directory attributes: userAccountControl, + msDS-User-Account-Control-Computed. This property is not supported + by AD LDS. + - Enabled - A property of type System.Boolean, for AD DS it is + derived from the directory attributes: userAccountControl, + msDS-User-Account-Control-Computed; for AD LDS it is derived from + the directory attribute msDS-UserAccountDisabled + - HomedirRequired - A property of type System.Boolean, derived from + the directory attributes: userAccountControl, + msDS-User-Account-Control-Computed. This property is not supported + by AD LDS. + - LastBadPasswordAttempt - A property of type System.DateTime, + derived from the directory attribute: badPasswordTime + - LastLogonDate - A property of type System.DateTime, derived from + the directory attribute: lastLogonTimestamp + - LockedOut - A property of type System.Boolean, for AD DS it is + derived from the directory attributes: userAccountControl, + msDS-User-Account-Control-Computed, lockoutTime; for AD LDS it is + derived from the directory attribute msDS-UserAccountDisabled + - MNSLogonAccount - A property of type System.Boolean, derived from + the directory attributes: userAccountControl, + msDS-User-Account-Control-Computed. This property is not supported + by AD LDS. + - PasswordExpired - A property of type System.Boolean, for AD DS it + is derived from the directory attributes: userAccountControl, + msDS-User-Account-Control-Computed; for AD LDS it is derived from + the directory attribute msDS-UserPasswordExpired + - PasswordLastSet - A property of type System.DateTime, derived from + the directory attribute: pwdLastSet + - PasswordNeverExpires - A property of type System.Boolean, for AD + LDS it is derived from the directory attributes: + userAccountControl, msDS-User-Account-Control-Computed; for AD LDS + it is derived from the directory attribute: + msDS-UserDontExpirePassword + - PasswordNotRequired - A property of type System.Boolean, for AD DS + it is derived from the directory attributes: userAccountControl, + msDS-User-Account-Control-Computed; for AD LDS it is derived from + the directory attribute: ms-DS-UserPasswordNotRequired + - PrimaryGroup - A property of type System.String, derived from the + directory attributes: primaryGroupID, objectSid. This property is + not supported by AD LDS. + - ServicePrincipalNames - A property of type System.String, derived + from the directory attribute: servicePrincipalName. This property + is not supported by AD LDS. + - TrustedForDelegation - A property of type System.Boolean, derived + from the directory attributes: userAccountControl, + msDS-User-Account-Control-Computed. This property is not supported + by AD LDS. + - TrustedToAuthForDelegation - A property of type System.Boolean, + derived from the directory attributes: userAccountControl, + msDS-User-Account-Control-Computed. This property is not supported + by AD LDS. + - UseDESKeyOnly - A property of type System.Boolean, derived from the + directory attributes: userAccountControl, + msDS-User-Account-Control-Computed. This property is not supported + by AD LDS. + - UserPrincipalName - A property of type System.String, derived from + the directory attribute: userPrincipalName + - ADComputer - Represents a computer and is derived from ADAccount. + An ADComputer may contain the following properties in addition to + those inherited from its parent. + - DNSHostName - A property of type System.String, derived from the + directory attribute: dNSHostName + - IPv4Address - A property of type System.String, derived from the + directory attribute: dNSHostName + - IPv6Address - A property of type System.String, derived from the + directory attribute: dNSHostName + - Location - A property of type System.String, derived from the + directory attribute: location + - ManagedBy - A property of type System.String, derived from the + directory attribute: managedBy + - OperatingSystem - A property of type System.String, derived from + the directory attribute: operatingSystem + - OperatingSystemHotfix - A property of type System.String, derived + from the directory attribute: operatingSystemHotfix + - OperatingSystemServicePack - A property of type System.String, + derived from the directory attribute: operatingSystemServicePack + - OperatingSystemVersion - A property of type System.String, + derived from the directory attribute: operatingSystemVersion + - ServiceAccount - A property of type System.String, derived from + the directory attribute: msDS-HostServiceAccount + - ADServiceAccount - Represents a managed service account; that is, + an Active Directory object of type msDS-ManagerdServiceAccount and + is derived from ADAccount. This class is not supported by AD LDS. + An ADServiceAccount may contain the following properties in + addition to those inherited from its parent. + - HostComputers - A property of type System.String, derived from + the directory attribute: msDS-HostServiceAccountBL + - ADUser - Represents a user (or iNetOrgPerson) and is derived from + ADAccount. An ADUser may contain the following properties in + addition to those inherited from its parent. + - City - A property of type System.String, derived from the + directory attribute: l + - Company - A property of type System.String, derived from the + directory attribute: company + - Country - A property of type System.String, derived from the + directory attribute: c + - Department - A property of type System.String, derived from the + directory attribute: department + - Division - A property of type System.String, derived from the + directory attribute: division + - EmailAddress - A property of type System.String, derived from the + directory attribute: mail + - EmployeeID - A property of type System.String, derived from the + directory attribute: employeeID + - EmployeeNumber - A property of type System.String, derived from + the directory attribute: employeeNumber + - Fax - A property of type System.String, derived from the + directory attribute: facsimileTelephoneNumber + - GivenName - A property of type System.String, derived from the + directory attribute: givenName + - HomeDirectory - A property of type System.String, derived from + the directory attribute: homeDirectory. This property is not + supported by AD LDS. + - HomeDrive - A property of type System.String, derived from the + directory attribute: homeDrive. This property is not supported by + AD LDS. + - HomePhone - A property of type System.String, derived from the + directory attribute: homePhone + - Initials - A property of type System.String, derived from the + directory attribute: initials + - LogonWorkstations - A property of type System.String, derived + from the directory attribute: userWorkstations. This property is + not supported by AD LDS. + - Manager - A property of type System.String, derived from the + directory attribute: manager + - MobilePhone - A property of type System.String, derived from the + directory attribute: mobile + - Office - A property of type System.String, derived from the + directory attribute: physicalDeliveryOfficeName + - OfficePhone - A property of type System.String, derived from the + directory attribute: telephoneNumber + - Organization - A property of type System.String, derived from the + directory attribute: o + - OtherName - A property of type System.String, derived from the + directory attribute: middleName + - POBox - A property of type System.String, derived from the + directory attribute: postOfficeBox + - PostalCode - A property of type System.String, derived from the + directory attribute: postalCode + - ProfilePath - A property of type System.String, derived from the + directory attribute: profilePath. This property is not supported + by AD LDS. + - ScriptPath - A property of type System.String, derived from the + directory attribute: scriptPath. This property is not supported + by AD LDS. + - SmartcardLogonRequired - A property of type System.Boolean, + derived from the directory attributes: userAccountControl, + msDS-User-Account-Control-Computed. This property is not + supported by AD LDS. + - State - A property of type System.String, derived from the + directory attribute: st + - StreetAddress - A property of type System.String, derived from + the directory attribute: streetAddress + - Surname - A property of type System.String, derived from the + directory attribute: sn + - Title - A property of type System.String, derived from the + directory attribute: title + - ADGroup -Represents a group and is derived from ADPrincipal. An + ADGroup may contain the following properties in addition to those + inherited from its parent. + - GroupCategory - A property of type + Microsoft.ActiveDirectory.Management.ADGroupCategory, derived from + the directory attribute: groupType + - GroupScope - A property of type + Microsoft.ActiveDirectory.Management.ADGroupScope, derived from the + directory attribute: groupType + - ManagedBy - A property of type System.String, derived from the + directory attribute: managedBy + - Members - A property of type System.String, derived from the + directory attribute: member + - ADDefaultDomainPasswordPolicy - Represents the domain-wide password policy + of an Active Directory domain and is derived from ADEntity. This class is + not supported by AD LDS. An ADDefaultDomainPasswordPolicy may contain the + following properties in addition to those inherited from its parent. + - ComplexityEnabled - A property of type System.Boolean, derived from the + directory attribute: pwdProperties + - DistinguishedName - A property of type System.String, derived from the + directory attribute: distinguishedName + - LockoutDuration - A property of type System.TimeSpan, derived from the + directory attribute: lockoutDuration + - LockoutObservationWindow - A property of type System.TimeSpan, derived + from the directory attribute: lockoutObservationWindow + - LockoutThreshold - A property of type System.Int32, derived from the + directory attribute: lockoutThreshold + - MaxPasswordAge - A property of type System.TimeSpan, derived from the + directory attribute: maxPwdAge + - MinPasswordAge - A property of type System.TimeSpan, derived from the + directory attribute: minPwdAge + - MinPasswordLength - A property of type System.Int32, derived from the + directory attribute: minPwdLength + - PasswordHistoryCount - A property of type System.Int32, derived from the + directory attribute: pwdHistoryLength + - ReversibleEncryptionEnabled - A property of type System.Boolean, derived + from the directory attribute: pwdProperties + - ADForest - Represents a Active Directory forest in AD DS or a Configuration + Set in AD LDS and is derived from ADEntity. This class is not supported by + AD LDS. An ADForest may contain the following properties in addition to + those inherited from its parent. + - ApplicationPartitions - A property of type System.String, derived from + the directory attribute: ApplicationPartitions + - CrossForestReferences - A property of type System.String, derived from + the directory attribute: CrossForestReferences + - DomainNamingMaster - A property of type System.String, derived from the + directory attribute: DomainNamingMaster + - Domains - A property of type System.String, derived from the directory + attribute: Domains + - ForestMode - A property of type System.Int32, derived from the directory + attribute: msDS-Behavior-Version + - GlobalCatalogs - A property of type System.String, derived from the + directory attribute: GlobalCatalogs + - Name - A property of type System.String, derived from the directory + attribute: name + - PartitionContainerName - A property of type System.String, derived from + the directory attribute: distinguishedName + - RootDomain - A property of type System.String, derived from the directory + attribute: RootDomain + - SchemaMaster - A property of type System.String, derived from the + directory attribute: SchemaMaster + - Sites - A property of type System.String, derived from the directory + attribute: Sites + - SPNSuffixes - A property of type System.String, derived from the + directory attribute: msDS-SPNSuffixes + - UPNSuffixes - A property of type System.String, derived from the + directory attribute: uPNSuffixes + - ADDirectoryServer - Represents a directory server used as either a domain + controller or an AD LDS instance and is derived from ADEntity. An + ADDirectoryServer may contain the following properties in addition to those + inherited from its parent. + - DefaultPartition - A property of type System.String, derived from the + directory attribute: DefaultPartition + - HostName - A property of type System.String, derived from the directory + attribute: HostName + - InvocationId - A property of type System.Guid, derived from the directory + attribute: InvocationId + - IPv4Address - A property of type System.String, derived from the + directory attribute: HostName + - IPv6Address - A property of type System.String, derived from the + directory attribute: HostName + - LdapPort - A property of type System.Int32, derived from the directory + attribute: LdapPort + - Name - A property of type System.String, derived from the directory + attribute: Name + - NTDSSettingsObjectDN - A property of type System.String, derived from the + directory attribute: NTDSSettingsObjectDN + - OperationMasterRoles - A property of type + Microsoft.ActiveDirectory.Management.ADOperationMasterRole, derived from + the directory attribute: OperationMasterRole + - Partitions - A property of type System.String, derived from the directory + attribute: Partitions + - ServerObjectDN - A property of type System.String, derived from the + directory attribute: ServerObjectDN + - ServerObjectGuid - A property of type System.Guid, derived from the + directory attribute: ServerObjectGuid + - Site - A property of type System.String, derived from the directory + attribute: Site + - SslPort - A property of type System.Int32, derived from the directory + attribute: SslPort + - ADDomainController - Represents a domain controller in AD DS and is + derived from ADDirectoryServer. An ADDomainController may contain the + following properties in addition to those inherited from its parent. + - ComputerObjectDN - A property of type System.String, derived from the + directory attribute: ComputerDN + - Domain - A property of type System.String, derived from the directory + attribute: Domain + - Enabled - A property of type System.Boolean, derived from the directory + attribute: Enabled + - Forest - A property of type System.String, derived from the directory + attribute: Forest + - IsGlobalCatalog - A property of type System.Boolean, derived from the + directory attribute: IsGlobalCatalog + - IsReadOnly - A property of type System.Boolean, derived from the + directory attribute: IsReadOnly + - OperatingSystem - A property of type System.String, derived from the + directory attribute: OSName + - OperatingSystemHotfix - A property of type System.String, derived from + the directory attribute: OSHotFix + - OperatingSystemServicePack - A property of type System.String, derived + from the directory attribute: OSServicepack + - OperatingSystemVersion - A property of type System.String, derived from + the directory attribute: OSVersion diff --git a/docset/winserver2019-ps/appx/Get-NonRemovableAppsPolicy.md b/docset/winserver2019-ps/appx/Get-NonRemovableAppsPolicy.md index d3190cccc2..8eb795743f 100644 --- a/docset/winserver2019-ps/appx/Get-NonRemovableAppsPolicy.md +++ b/docset/winserver2019-ps/appx/Get-NonRemovableAppsPolicy.md @@ -1,5 +1,6 @@ --- -audiencems.localizationpriority: ITPro +audience: ITPro +ms.localizationpriority: Low description: Use this topic to help prevent the uninstall of specific Windows apps with Windows PowerShell. external help file: Microsoft.Windows.Appx.PackageManager.Commands.dll-help.xml Module Name: Appx diff --git a/docset/winserver2019-ps/appx/Set-NonRemovableAppsPolicy.md b/docset/winserver2019-ps/appx/Set-NonRemovableAppsPolicy.md index c71cace1de..219553197c 100644 --- a/docset/winserver2019-ps/appx/Set-NonRemovableAppsPolicy.md +++ b/docset/winserver2019-ps/appx/Set-NonRemovableAppsPolicy.md @@ -1,5 +1,6 @@ --- -audiencems.localizationpriority: ITPro +audience: ITPro +ms.localizationpriority: Low description: Use this topic to help prevent the uninstall of specific Windows apps with Windows PowerShell. external help file: Microsoft.Windows.Appx.PackageManager.Commands.dll-help.xml Module Name: Appx diff --git a/docset/winserver2019-ps/hyper-v/Get-VMNetworkAdapter.md b/docset/winserver2019-ps/hyper-v/Get-VMNetworkAdapter.md index 48b82a48ca..85aada7085 100644 --- a/docset/winserver2019-ps/hyper-v/Get-VMNetworkAdapter.md +++ b/docset/winserver2019-ps/hyper-v/Get-VMNetworkAdapter.md @@ -203,7 +203,7 @@ Accept wildcard characters: False ### -VM Specifies the virtual machine whose virtual network adapters are to be retrieved. -. The asterisk, "*", is the wildcard. +The asterisk, "*", is the wildcard. If it is specified the cmdlet returns virtual network adapters from every virtual machine in the system. ```yaml diff --git a/docset/winserver2022-ps/activedirectory/About/About.md b/docset/winserver2022-ps/activedirectory/About/About.md new file mode 100644 index 0000000000..449df28850 --- /dev/null +++ b/docset/winserver2022-ps/activedirectory/About/About.md @@ -0,0 +1,26 @@ +--- +description: About articles for the ActiveDirectory module. +Help Version: 3.1.0.0 +Locale: en-US +ms.date: 07/03/2024 +title: About articles +--- +# About topics + +## Description + +About topics cover a range of concepts about PowerShell. + +## About Topics + +### [about_ActiveDirectory](about_ActiveDirectory.md) +The Active Directory module is a command line interface for managing Active Directory. + +### [about_ActiveDirectory_Filter](about_ActiveDirectory_Filter.md) +Describes the syntax and behavior of the search filter supported by the Active Directory module for Windows PowerShell. + +### [about_ActiveDirectory_Identity](about_ActiveDirectory_Identity.md) +The Active Directory module for Windows PowerShell objects have a range of identifying attributes that are used for search and retrieval. + +### [about_ActiveDirectory_ObjectModel](about_ActiveDirectory_ObjectModel.md) +Describes the object model of the Active Directory module for Windows PowerShell. diff --git a/docset/winserver2022-ps/activedirectory/About/about_ActiveDirectory.md b/docset/winserver2022-ps/activedirectory/About/about_ActiveDirectory.md new file mode 100644 index 0000000000..1b7183dcd2 --- /dev/null +++ b/docset/winserver2022-ps/activedirectory/About/about_ActiveDirectory.md @@ -0,0 +1,81 @@ +--- +title: about_ActiveDirectory +ms.date: 04/22/2013 +description: The Active Directory module is a command line interface for managing Active Directory. +Locale: en-US +schema: 2.0.0 +--- + +# about_ActiveDirectory + +## SHORT DESCRIPTION + +The Active Directory module is a command line interface for managing Active +Directory. + +## LONG DESCRIPTION + +The Active Directory module for Windows PowerShell is for IT Professionals who +are administering and interfacing with Active Directory. The Active Directory +module provides an efficient way to complete many administrative, +configuration, and diagnostic tasks across Active Directory Domain Services (AD +DS) and Active Directory Lightweight Directory Services (AD LDS) instances in +their environments. The Active Directory module includes a set of Windows +PowerShell cmdlets and a provider. The provider exposes the Active Directory +database through a hierarchical navigation system, which is very similar to the +file system. As with drives in a file system, such as C:, you can connect +Windows PowerShell drives to Active Directory domains and AD LDS, as well as +Active Directory snapshots. + +### Coverage of Active Directory Module Cmdlets + +Create, Read, Update, and Delete actions are supported for Active Directory +objects by cmdlets such as `New-ADUser`, `Get-ADOrganizationalUnit`, +`Set-ADComputer`, and `Remove-ADUser`. + +Account and Password Policy Management are supported by cmdlets such as +`Enable-ADAccount`, `Unlock-ADAccount`, `New-ADServiceAccount`, +`Set-ADAccountControl`, and `Remove-ADFineGrainedPasswordPolicy`. + +Domain and Forest Management is supported by cmdlets such as `Get-ADForest`, +`Set-ADForest`, `Set-ADForestMode`, `Enable-ADOptionalFeature`, +`Get-ADDomainController`, and `Get-ADDomain`. + +### Listing the Active Directory Module Cmdlets + +To get a list of all of the Active Directory module cmdlets, run + +```powershell +Get-Command -Module ActiveDirectory +``` + +### Getting Started + +Getting started with the Active Directory module for Windows PowerShell is as +easy as clicking the following shortcut: + +Run the following command in any Windows PowerShell prompt to import the Active +Directory module: + +```powershell +Import-Module ActiveDirectory +``` + +### Overview and Conceptual Topics + +The first two of these topics offer a high level overview of the Active +Directory module and the Active Directory Provider. + +- For a brief introduction to the Active Directory provider for Windows + PowerShell, see [ActiveDirectory](/powershell/module/activedirectory). +- The following topics are conceptual support topics for the Active Directory + module cmdlets. + - For an introduction to the **Identity** parameter, which is used by the + Active Directory module cmdlets to identify objects in the directory, see + [about_ActiveDirectory_Identity](about_ActiveDirectory_Identity.md). + - For an introduction to the **Filter** parameter which is used by Active + Directory module cmdlets to search for objects in the directory, see + [about_ActiveDirectory_Filter](about_ActiveDirectory_Filter.md). + - For an introduction to the .NET Framework-based object model implemented by + the Active Directory module, see + [about_ActiveDirectory_ObjectModel](about_ActiveDirectory_ObjectModel.md). diff --git a/docset/winserver2022-ps/activedirectory/About/about_ActiveDirectory_Filter.md b/docset/winserver2022-ps/activedirectory/About/about_ActiveDirectory_Filter.md new file mode 100644 index 0000000000..23a83c0a0a --- /dev/null +++ b/docset/winserver2022-ps/activedirectory/About/about_ActiveDirectory_Filter.md @@ -0,0 +1,351 @@ +--- +title: about_ActiveDirectory_Filter +ms.date: 04/22/2013 +description: Describes the syntax and behavior of the search filter supported by the Active Directory module for Windows PowerShell. +Locale: en-US +schema: 2.0.0 +--- + +# about_ActiveDirectory_Filter + +## SHORT DESCRIPTION + +Describes the syntax and behavior of the search filter supported by the Active +Directory module for Windows PowerShell. + +## LONG DESCRIPTION + +Most get-AD* Active Directory module cmdlets use the Filter parameter to search +for objects. The Filter parameter has been implemented to replace the function +of the LDAP Filter and adds support for PowerShell variables, rich data types, +improved error checking and an Active Directory extended form of the PowerShell +Expression Language. + + +- Support for LDAP Filter Syntax + + The LDAP filter syntax is supported through the **LDAPFilter** parameter. You + will find LDAP filter examples along with the new Active Directory module + filter examples in the Filter Examples section of this topic. + + +- Search Breadth and Depth + + The breadth and depth of your filter-driven search can be modified by two + Active Directory module cmdlet parameters: **SearchBase** and **SearchScope**. + + When within the context of the Active Directory provider, if the + **Searchbase** parameter is not specified, **SearchBase** will default to the + current path. When not running under the Active Directory provider, the + **SearchBase** will default to the server's **DefaultNamingContext**. + + The **SearchScope** parameter defaults to the value `Subtree`, of the + enumerated type **ADSearchScope**. + + For more information, see the **SearchBase** and **SearchScope** parameter + descriptions on any `Get-AD*` cmdlet. + +- Search Result Behavior + + The behavior of the Active Directory module when returning results of a + search is modified by two cmdlet parameters: **ResultPageSize** and + **ResultSetSize**. + + **ResultSetSize** controls the maximum number of returned objects. + + **ResultPageSize** specifies the maximum number of objects for each returned + page of information. + + See the **ResultPageSize** and **ResultSetSize** parameter descriptions on + any `Get-AD*` cmdlet for more information. + + +- Timeout Behavior + + The following statements specify timeout conditions within the Active + Directory module and describe what can be done about a timeout them. + + The default Active Directory module timeout for all operations is 2 + minutes. + + For search operation, the Active Directory module uses paging control + with a 2-minute timeout for each page search. + + > [!NOTE] + > Because a search may involve multiple server page requests the overall + > search time may exceed 2 minutes. + + A **TimeoutException** error indicates that a timeout has occurred. + + For a search operation, you can choose to use a smaller page size, set with + the **ResultPageSize** parameter, if you are getting a **TimeoutException** + error. + + If after trying these changes you are still getting a **TimeoutException** + error, consider optimizing your filter using the guidance in the + Optimizing Filters section of this topic. + + +- Optimizing Filters + + You can enhance the search filter behavior by using these guidelines. + + - Avoid using the **Recursive** parameter as it intensifies resource usage of + the search operation. + - Avoid using bitwise AND operators and bitwise OR operators. For more + information, see the Supported Operators section of this topic. + - Avoid using the logical NOT operator. + - Break down your search into multiple queries with narrower conditions. + + For a full description of filter syntax and usage, see the Filter Syntax + section of this topic. + + +## Filter Examples + +The following section shows many examples of filter use in common queries. + +### Example 1 - Get all entries: + +- LDAP Filter Equivalent: `(objectClass=*)` + +```powershell +Get-ADObject -Filter 'ObjectClass -like "*"' +``` + +### Example 2 - Get entries containing "bob" somewhere in the common name + +- LDAP Filter Equivalent: `(cn=*bob*)` + +```powershell +Get-ADObject -Filter 'CN -like "*bob*"' +``` + +### Example 3 - Get entries with a bad password count greater than five + +- LDAP Filter Equivalent: `(&(!badpwdcount<=5)(badpwdcount=*))` + +```powershell +Get-ADUser -Filter 'badpwdcount -ge 5' +``` + +### Example 4 - Get all users with an e-mail attribute + +- LDAP Filter Equivalent: `(&(objectClass=user)(email=*))` + +```powershell +Get-ADUser -filter 'email -like "*"' +``` + +-or- + +```powershell +Get-ADObject -filter 'email -like "*" -and ObjectClass -eq "user"' +``` + +### Example 5 - Get all user entries with an e-mail attribute and a surname equal to "smith": + +- LDAP Filter Equivalent: `(&(sn=smith)(objectClass=user)(email=*))` + +```powershell +Get-ADUser -Filter 'Email -like "*" -and SurName -eq "smith"' +``` + +-or- + +```powershell +Get-ADUser -Filter 'Email -like "*" -and sn -eq "smith"' +``` + + +### Example 6 - Get all user entries with a common name that starts with "andy" and users with a common name of "steve" or "margaret" + +- LDAP Filter Equivalent: `(&(objectClass=user) | (cn=andy*)(cn=steve)(cn=margaret))` + +```powershell +Get-ADUser -Filter 'CN -like "andy*" -or CN -eq "steve" -or CN -eq "margaret"' +``` + + +This example demonstrates a more complex logic and the use of precedence +control via parenthesis. + +```powershell +Get-ADObject -Filter 'objectClass -eq "user" -and (CN -like "andy*" -or CN -eq "steve" -or CN -eq "margaret")' +``` + +### Example 7 - Get all entries without an e-mail attribute + +- LDAP Filter Equivalent: `(!(email=*))` + +```powershell +Get-ADUser -Filter '-not Email -like "*"' +``` + +-or- + +```powershell +Get-ADUser -Filter 'Email -notlike "*"' +``` + +### Example 8 - Get all users who did not logon since January 1, 2007 + +- LDAP Filter Equivalent: `(&(lastlogon<=X)(objectClass=user))` where X is + number of 100-nanosecond slices since Jan 1st 1601 + +```powershell +$date = new-object System.DateTime -ArgumentList @(2007,1,1,0,0,0) +Get-ADUser -Filter '-not LastLogon -le $date' +``` + +### Example 9 - Get all users who have logged on in the last 5 days + +- LDAP Filter Equivalent: + + ``` + (&(lastLogon>=128812906535515110) + (objectClass=user)(!(objectClass=computer))) + ``` + +```powershell +$date = (get-date) - (new-timespan -days 5) +Get-ADUser -Filter 'lastLogon -gt $date' +``` + +### Example 10 - Search for group objects that have the ADS_GROUP_TYPE_SECURITY_ENABLED flag set + +- LDAP Filter Equivalent: + `(&(objectCategory=group)(groupType:1.2.840.113556.1.4.803:=2147483648))` + +The following example query string searches for group objects that have the +ADS_GROUP_TYPE_SECURITY_ENABLED flag set. Be aware that the decimal value of +ADS_GROUP_TYPE_SECURITY_ENABLED (0x80000000 = 2147483648) is used for the +comparison value. + +```powershell +Get-ADGroup -filter 'groupType -band 0x80000000' +``` + +### Example 11 - Search the ancestry of an object + +- LDAP Filter Equivalent: + `(memberof:1.2.840.113556.1.4.1941:=(cn=Group1,OU=groupsOU,DC=x)))` + +The LDAP_MATCHING_RULE_IN_CHAIN is a matching rule OID that is designed to +provide a method to look up the ancestry of an object. Many applications using +Active Directory and AD LDS usually work with hierarchical data, which is +ordered by parent-child relationships. Previously, applications performed +transitive group expansion to figure out group membership, which used a lot of +network bandwidth. Applications made multiple round-trips to figure out if an +object fell "in the chain" if a link were traversed through to the end. + +An example of such a query is one designed to check if a user, "user1" is a +member of group "group1". "user1" may not be a direct member of group1. It +could be a member of some other group, which is a member of "group1". + +You would set the base to the user DN and the scope to base, and use the query: + +```powershell +Get-ADUser -Filter 'memberOf -RecursiveMatch "CN=Administrators, CN=Builtin,DC=Fabrikam,DC=com"' -SearchBase "CN=Administrator,CN=Users,DC=Fabrikam,DC=com" +``` + +## Filter Syntax + +The following syntax descriptions use Backus-Naur form to show the PowerShell +Expression Language for the Filter parameter. + +```Syntax + ::= "{" "}" + + ::= | + | + + + ::= | + "(" ")" + + ::= "-eq" | "-le" | "-ge" | "-ne" | "-lt" | "-gt" | + "-approx" | "-bor" | "-band" | "-recursivematch" | "-like" | + "-notlike" + + ::= "-and" | "-or" + + ::= "-not" + + ::= | + +::= < this value will be compared to the object data for + attribute using the specified filter operator +``` + + +## Supported Operators + +The following table shows frequently used search filter operators. + +| Operator | Description | LDAP Equivalent | +| ----------------- | -------------------------------------- | -------------------------- | +| `-eq` | Equal to. Wildcards not supported. | = | +| `-ne` | Not equal to. Wildcards not supported. | !x = y | +| `-approx` | Approximately equal to | ~= | +| `-le` | Lexicographically less than | <= | +| | or equal to | | +| `-lt` | Lexicographically less than | !x >= y | +| `-ge` | Lexicographically greater | >= | +| | than or equal to | | +| `-gt` | Lexicographically greater than | !x <= y | +| | | | +| `-and` | AND | & | +| `-or` | OR | | +| `-not` | NOT | ! | +| `-bor` | Bitwise OR | :1.2.840.113556.1.4.804:= | +| `-band` | Bitwise AND | :1.2.840.113556.1.4.803:= | +| `-recursivematch` | Use LDAP_MATCHING_RULE_IN_CHAIN | :1.2.840.113556.1.4.1941:= | +| `-like` | Similar to `-eq` and supports | = | +| | wildcard comparison. The only | | +| | wildcard character supported is: `*` | | +| `-notlike` | Not like. Supports wild | !x = y | +| | card comparison. | | + +> [!NOTE] +> PowerShell wildcards, other than "*", such as "?" are not supported by the +> **Filter** parameter syntax. + +### Operator Precedence + +The following listing shows the precedence of operators for filters from +highest to lowest. + +- Highest precedence: `-eq`, `-ge`, `-le`, `-approx`, `-band`, `-bor`, + `-recursivematch`, `-ne`, `-like`, `-not`, `-and` +- Lowest precedence: `-or` + +### Special Characters + +The following escape sequence should be used for specifying special characters +in AD Filter STRING data, that is, data enclosed in double or single quotes. + +| ASCII Character | Escape sequence substitute | +| --------------- | --------------------------------------------------- | +| `"` | `` `" `` (This escape sequence is only required if | +| | STRING data is enclosed in double quotes.) | +| `'` | `''` (This escape sequence is only required if | +| | STRING data is enclosed in single quotes.) | +| NUL | `\00` (This is a standard LDAP escape sequence.) | +| `\` | `\5c` (This is a standard LDAP escape sequence.) | + +### LDAP Special Characters + +ADFilter parser will automatically convert all the below characters found in +STRING data, that is data enclosed in " " or ' ' to their LDAP escape sequence. +End users need not know about these LDAP escape sequence. + +| ASCII Character | Escape sequence substitute | +| --------------- | ----------------------------------------------- | +| `*` | `\2a` (Character `*` will only be converted in | +| | -eq and -ne comparisons Users should use | +| | -like and -notlike operators for wildcard | +| | comparison.) | +| `(` | `\28` | +| `)` | `\29` | +| `/` | `\2f` | diff --git a/docset/winserver2022-ps/activedirectory/About/about_ActiveDirectory_Identity.md b/docset/winserver2022-ps/activedirectory/About/about_ActiveDirectory_Identity.md new file mode 100644 index 0000000000..c007277b19 --- /dev/null +++ b/docset/winserver2022-ps/activedirectory/About/about_ActiveDirectory_Identity.md @@ -0,0 +1,196 @@ +--- +title: about_ActiveDirectory_Identity +ms.date: 04/22/2013 +description: This article lists the identifying attributes that are used for search and retrieval supported by the Active Directory module for Windows PowerShell. +Locale: en-US +schema: 2.0.0 +--- + +# about_ActiveDirectory_Identity + +## SHORT DESCRIPTION + +The Active Directory module for Windows PowerShell objects have a range of +identifying attributes that are used for search and retrieval. + +## LONG DESCRIPTION + +In order to identify the objects in Active Directory, each object has +attributes that can be used as identifiers. In the Active Directory module, the +value of the identity of an object can be passed using the Identity parameter. +Each object type has its own set of possible types and values for use by the +Identity parameter. See the detailed description of the Identity parameter of +the given cmdlet for more information about its usage. + +When searching with the Active Directory module cmdlets, the value of the +Identity parameter, along with the values of the Server and Partition +parameters, is used to uniquely identify a single object. The Server parameter +is used to locate which server to connect with. The Partition parameter further +narrows the search to a specific partition. The Identity parameter then +resolves to a single unique object in the partition. + +Note that using the Security Accounts Manager (SAM) Account Name +(**sAMAccountName**) when targeting a global catalog port, you will not find a +user in a different domain if you are using the Identity parameter + +If more than one object is found using identity resolution, the Active +Directory module throws an error. + +For more information about the Server and Partition parameters, see the help +topics for the individual cmdlets where they are used, such as `Get-ADUser`, by +typing: + +```powershell +Get-Help Get-ADUser +``` + +### Objects and Identities + +Each object has a list of attributes that can be used as an identity for that +object. Additionally, if the object inherits from another object, then the +parent object's identities can also be used as the child object's identities. +For more information on the Active Directory object hierarchy, see +[about_ActiveDirectory_ObjectModel](about_ActiveDirectory_ObjectModel.md). + +> [!NOTE] +> For Active Directory Provider cmdlets, only an object's 'Distinguished Name' +> or 'Relative Distinguished Name' can be used as the identity. For a list of +> Active Directory Provider cmdlets, see ActiveDirectory. + +### Identity Attributes + +The following is a list of identity attributes by object type. + +- ADAccount + - Distinguished Name + - GUID (objectGUID) + - Security Identifier (objectSid) + - SAM Account Name (sAMAccountName) + +- ADComputer + - Distinguished Name + - GUID (objectGUID) + - Security Identifier (objectSid) + - Security Accounts Manager Account Name (sAMAccountName) + +- ADDirectoryServer + - Name of the server object (name) + - For AD LDS instances the syntax of a name is `$` + - For other Active Directory instances, use the value of the name property. + - Distinguished Name of the NTDS Settings object + - Distinguished Name of the server object that represents the directory + server. + - GUID (objectGUID) of server object under the configuration partition. + - GUID (objectGUID) of NTDS settings object under the configuration partition + +- ADDomain + - Distinguished Name + - GUID + - Security Identifier + - DNS domain name + - NetBIOS domain name + +- ADDomainController + - GUID (objectGUID) + - IPV4Address + - Global IPV6Address + - DNS Host Name (dNSHostName) + - Name of the server object + - Distinguished Name of the NTDS Settings object + - Distinguished Name of the server object that represents the domain controller + - GUID of NTDS settings object under the configuration partition + - GUID of server object under the configuration partition + - Distinguished Name of the computer object that represents the domain controller. + +- ADFineGrainedPasswordPolicy + - Distinguished Name + - GUID (objectGUID) + - Name (name) + +- ADForest + - Fully qualified domain name + - DNS host name + - NetBIOS name + +- ADGroup + - Distinguished Name + - GUID (objectGUID) + - Security Identifier (objectSid) + - Security Accounts Manager (SAM) Account Name (sAMAccountName) + +- ADObject + - Distinguished Name + - GUID (objectGUID) + +- ADOptionalFeature + - Distinguished Name + - Name (name) + - Feature GUID (featureGUID) + - GUID (objectGUID) + +- ADOrganizationalUnit + - Distinguished Name + - GUID (objectGUID) + +- ADPrincipal + - Distinguished Name + - GUID (objectGUID) + - Security Identifier (objectSid) + - SAM Account Name (sAMAccountName) + +- ADServiceAccount + - Distinguished Name + - GUID (objectGUID) + - Security Identifier (objectSid) + - SAM Account Name (sAMAccountName) + +- ADUser + - Distinguished Name + - GUID (objectGUID) + - Security Identifier (objectSid) + - SAM User Name (sAMUserName) + + +### Identities Formats + +Active Directory module objects have a range of identity attributes. Below is a +list of these, their types and formats. + +- Distinguished Name + - Example: CN=SaraDavis,CN=Europe,CN=Users, DC=corp,DC=contoso,DC=com + +- DNS domain name + - Example: redmond.corp.contoso.com + +- DNS Host Name (dNSHostName) + - Example: corp-DC01.corp.contoso.com + +- Feature GUID (featureGUID) + - Example: 599c3d2e-f72d-4d20-8a88-030d99495f20 + +- Fully qualified domain name + - Example: corp.contoso.com + +- Global IPV6Address + - Example: 2001:4898:0:fff:200:5efe:157.59.132.61 + +- GUID (objectGUID) + - Example: 599c3d2e-f72d-4d20-8a88-030d99495f20 + +- IPV4Address + - Example:157.59.132.61 + +- NetBIOS domain name + - Example: redmond + +- Name of the server object + - Example: corp-DC01$ + +- SAM Account Name (sAMAccountName) + - Example: saradavisreports + +- Security Identifier (objectSid) + - Example: S-1-5-21-3165297888-301567370-576410423-1103 + +- Name + - Example: Recycle Bin Feature diff --git a/docset/winserver2022-ps/activedirectory/About/about_ActiveDirectory_ObjectModel.md b/docset/winserver2022-ps/activedirectory/About/about_ActiveDirectory_ObjectModel.md new file mode 100644 index 0000000000..8535a97464 --- /dev/null +++ b/docset/winserver2022-ps/activedirectory/About/about_ActiveDirectory_ObjectModel.md @@ -0,0 +1,595 @@ +--- +title: about_ActiveDirectory_ObjectModel +ms.date: 04/22/2013 +description: Describes the object model of the Active Directory module for Windows PowerShell. +Locale: en-US +schema: 2.0.0 +--- + +# about_ActiveDirectory_ObjectModel + +## SHORT DESCRIPTION +Describes the object model of the Active Directory module for Windows +PowerShell. + +## LONG DESCRIPTION + +This topic explains the Active Directory module classes and their properties +used to model actual Active Directory attributes. It also outlines the class +hierarchy constructed from its Active Directory counterpart. The object model +establishes a data foundation for all the operations supported by Active +Directory module cmdlets. + +### Class Hierarchy + +The following list shows the class hierarchy defined in the Active Directory +module object model, with class inheritance implied by indentation. This +inheritance model allows for Active Directory cmdlets to accept a range of +object types as input. This means, for example, that the cmdlet +Get-ADPrincipalGroupMembership can accept as input any of the following +objects: ADGroup, ADAccount, ADComputer, ADServiceAccount or ADUser. This works +because of the inheritance model and guarantees that an ADUser object has all +of the properties of an ADPrincipal object. + +``` +ADEntity + ADRootDSE + ADObject + ADFineGrainedPasswordPolicy + ADOptionalFeature + ADOrganizationalUnit + ADPartition + ADDomain + ADPrincipal + ADAccount + ADComputer + ADServiceAccount + ADUser + ADGroup + ADDefaultDomainPasswordPolicy + ADForest + ADDirectoryServer + ADDomainController +``` + +### Active Directory Module Classes + +The following listing shows every Active Directory module class from the class +hierarchy listing. Each class defines a set of properties, some of which are +LDAP attributes that are retrieved by default and some are new properties +created specifically for the Active Directory module. These new properties are +derived from one or more LDAP attributes as outlined in the class listings. + + +- ADEntity - The base level class from which all other classes are derived. + - ADRootDSE - Represents the rootDSE and is derived from ADEntity. An + ADRootDSE may contain the following properties in addition to those + inherited from its parent. + - ConfigurationNamingContext - A property of type System.String, derived + from the directory attribute ConfigurationNamingContext + - CurrentTime - A property of type System.DateTime, derived from the + directory attribute CurrentTime + - DefaultNamingContext - A property of type System.String, derived from the + directory attribute DefaultNamingContext + - DnsHostName - A property of type System.String, derived from the + directory attribute DnsHostName + - DomainControllerFunctionality - A property of type + ADDomainControllerMode, derived from the directory attribute + DomainControllerFunctionality + - DomainFunctionality - A property of type ADDomainMode, derived from the + directory attribute DomainFunctionality + - DsServiceName - A property of type System.String, derived from the + directory attribute DsServiceName + - ForestFunctionality - A property of type ADForestMode, derived from the + directory attribute ForestFunctionality + - GlobalCatalogReady - A property of type System.Boolean, derived from the + directory attribute GlobalCatalogReady + - HighestCommittedUSN - A property of type System.Long, derived from the + directory attribute HighestCommittedUSN + - LdapServiceName - A property of type System.String, derived from the + directory attribute LdapServiceName + - NamingContexts - A property of type System.String, derived from the + directory attribute NamingContexts + - RootDomainNamingContext - A property of type System.String, derived from + the directory attribute RootDomainNamingContext + - SchemaNamingContext - A property of type System.String, derived from the + directory attribute SchemaNamingContext + - ServerName - A property of type System.String, derived from the directory + attribute ServerName + - SubschemaSubentry - A property of type ADObject, derived from the + directory attribute SubschemaSubentry + - SupportedCapabilities - A property of type ADObjectIdentifier, derived + from the directory attribute SupportedCapabilities + - SupportedControl - A property of type ADObjectIdentifier, derived from + the directory attribute SupportedControl + - SupportedLDAPPolicies - A property of type System.String, derived from + the directory attribute SupportedLDAPPolicies + - SupportedLDAPVersion - A property of type System.Int, derived from the + directory attribute SupportedLDAPVersion + - SupportedRootDSEOperations - A property of type + ADPropertyValueCollection, derived from the directory attribute + SupportedRootDSEOperations + - SupportedSASLMechanisms - A property of type System.String, derived from + the directory attribute SupportedSASLMechanisms + - Syncronized - A property of type System.Boolean, derived from the + directory attribute IsSynchronized. + - ADObject - Represents any object in Active Directory and is derived from + ADEntity. An ADObject may contain the following properties in addition to + those inherited from its parent. + - CanonicalName - A property of type System.String, derived from the + directory attribute: canonicalName + - CN - A property of type System.String, derived from the directory + attribute: cn + - Created - A property of type System.DateTime, derived from the directory + attribute: createTimeStamp + - Deleted - A property of type System.Boolean, derived from the directory + attribute: isDeleted + - Description - A property of type System.String, derived from the + directory attribute: description + - DisplayName - A property of type System.String, derived from the + directory attribute: displayName + - DistinguishedName - A property of type System.String, derived from the + directory attribute: distinguishedName + - LastKnownParent - A property of type System.String, derived from the + directory attribute: lastKnownParent + - Modified - A property of type System.DateTime, derived from the directory + attribute: modifyTimeStamp + - Name - A property of type System.String, derived from the directory + attribute: name + - ObjectCategory - A property of type System.String, derived from the + directory attribute: objectCategory + - ObjectClass - A property of type System.String, derived from the + directory attribute: objectClass + - ObjectGUID - A property of type System.Guid, derived from the directory + attribute: objectGUID + - ProtectedFromAccidentalDeletion - A property of type System.Boolean, + derived from the directory attributes: nTSecurityDescriptor, + sdRightsEffective, instanceType, isDeleted + - ADFineGrainedPasswordPolicy Represents a fine grained password policy + object; that is, an AD object of type msDS-PasswordSettings in AD DS and + is derived from ADObject. This class is not supported by AD LDS. An + ADFineGrainedPasswordPolicy may contain the following properties in + addition to those inherited from its parent. + - AppliesTo - A property of type System.String, derived from the + directory attribute: msDS-PSOAppliesTo + - ComplexityEnabled - A property of type System.Boolean, derived from the + directory attribute: msDS-PasswordComplexityEnabled + - LockoutDuration - A property of type System.TimeSpan, derived from the + directory attribute: msDS-LockoutDuration + - LockoutObservationWindow - A property of type System.TimeSpan, derived + from the directory attribute: msDS-LockoutObservationWindow + - LockoutThreshold - A property of type System.Int32, derived from the + directory attribute: msDS-LockoutThreshold + - MaxPasswordAge - A property of type System.TimeSpan, derived from the + directory attribute: msDS-MaximumPasswordAge + - MinPasswordAge - A property of type System.TimeSpan, derived from the + directory attribute: msDS-MinimumPasswordAge + - MinPasswordLength - A property of type System.Int32, derived from the + directory attribute: msDS-MinimumPasswordLength + - PasswordHistoryCount - A property of type System.Int32, derived from + the directory attribute: msDS-PasswordHistoryLength + - Precedence - A property of type System.Int32, derived from the + directory attribute: msDS-PasswordSettingsPrecedence + - ReversibleEncryptionEnabled - A property of type System.Boolean, + derived from the directory attribute: + msDS-PasswordReversibleEncryptionEnabled + - ADOptionalFeature Represents an optional feature, an Active Directory + object of type msDS-OptionalFeature, and is derived from ADObject. An + ADOptionalFeaturemay contain the following properties in addition to + those inherited from its parent. + - EnabledScopes - A property of type System.String, derived from the + directory attribute: msDS-EnabledFeatureBL + - FeatureGUID - A property of type System.Guid, derived from the + directory attribute: msDS-OptionalFeatureGUID + - FeatureScope - A property of type System.Int32, derived from the + directory attribute: msDS-OptionalFeatureFlags + - IsDisableable - A property of type System.Boolean, derived from the + directory attribute: msDS-OptionalFeatureFlags + - RequiredDomainMode - A property of type + Microsoft.ActiveDirectory.Management.ADDomainMode, derived from the + directory attribute: msDS-RequiredDomainBehaviorVersion + - RequiredForestMode - A property of type + Microsoft.ActiveDirectory.Management.ADForestMode, derived from the + directory attribute: msDS-RequiredForestBehaviorVersion + - ADOrganizationalUnit Represents an organizationalUnit (OU) object and is + derived from ADObject. An ADOrganizationalUnit may contain the following + properties in addition to those inherited from its parent. + - City - A property of type System.String, derived from the directory + attribute: l + - Country - A property of type System.String, derived from the directory + attribute: c + - LinkedGroupPolicyObjects - A property of type System.String, derived + from the directory attribute: gpLink. This property is not supported on + AD LDS. + - ManagedBy - A property of type System.String, derived from the + directory attribute: managedBy + - PostalCode - A property of type System.String, derived from the + directory attribute: postalCode + - State - A property of type System.String, derived from the directory + attribute: st + - StreetAddress - A property of type System.String, derived from the + directory attribute: street + - ADPartition - Represents a naming context, Configuration, Schema, Domain + or Application Partition(ND NC) and is derived from ADObject. This class + is not supported by AD LDS. An ADPartition may contain the following + properties in addition to those inherited from its parent. + - DeletedObjectsContainer - A property of type System.String, derived + from the directory attribute: DeletedObjectsContainer + - DNSRoot - A property of type System.String, derived from the directory + attribute: DNSRoot + - LostAndFoundContainer - A property of type System.String, derived from + the directory attribute: LostAndFoundContainer + - QuotasContainer - A property of type System.String, derived from the + directory attribute: QuotasContainer + - ReadOnlyReplicaDirectoryServers - A property of type System.String, + derived from the directory attribute: ReadOnlyReplicaDirectoryServers + - ReplicaDirectoryServers - A property of type System.String, derived + from the directory attribute: ReplicaDirectoryServers + - SubordinateReferences - A property of type System.String, derived from + the directory attribute: SubordinateReferences + - ADDomain - Represents a domain in AD DS or an instance in AD LDS; for + example, an Active Directory object of type domainDNS and is derived + from ADPartition. This class is not supported by AD LDS. An ADDomain + may contain the following properties in addition to those inherited + from its parent. + - AllowedDNSSuffixes - A property of type System.String, derived from + the directory attribute: msDS-AllowedDNSSuffixes + - ChildDomains - A property of type System.String, derived from the + directory attribute: ChildDomains + - ComputersContainer - A property of type System.String, derived from + the directory attribute: ComputersContainer + - DomainControllersContainer - A property of type System.String, + derived from the directory attribute: DomainControllersContainer + - DomainMode - A property of type System.Int32, derived from the + directory attribute: msDS-Behavior-Version + - DomainSID - A property of type + System.Security.Principal.SecurityIdentifier, derived from the + directory attribute: objectSid + - ForeignSecurityPrincipalsContainer - A property of type + System.String, derived from the directory attribute: + ForeignSecurityPrincipalsContainer + - Forest - A property of type System.String, derived from the directory + attribute: Forest + - InfrastructureMaster - A property of type System.String, derived from + the directory attribute: InfrastructureMaster + - LastLogonReplicationInterval - A property of type System.TimeSpan, + derived from the directory attribute: msDS-LogonTimeSyncInterval + - LinkedGroupPolicyObjects - A property of type System.String, derived + from the directory attribute: LinkedGroupPolicyObjects + - ManagedBy - A property of type System.String, derived from the + directory attribute: managedBy + - NetBIOSName - A property of type System.String, derived from the + directory attribute: NetBIOSName + - ParentDomain - A property of type System.String, derived from the + directory attribute: ParentDomain + - PDCEmulator - A property of type System.String, derived from the + directory attribute: PDCEmulator + - RIDMaster - A property of type System.String, derived from the + directory attribute: RIDMaster + - SystemsContainer - A property of type System.String, derived from the + directory attribute: SystemsContainer + - UsersContainer - A property of type System.String, derived from the + directory attribute: UsersContainer + - ADPrincipal - Represents a security principal, which is an Active + Directory object of type user, computer, group or iNetOrgPerson and is + derived from ADObject. An ADPrincipal may contain the following + properties in addition to those inherited from its parent. + - HomePage - A property of type System.String, derived from the + directory attribute: wWWHomePage + - MemberOf - A property of type System.String, derived from the + directory attribute: memberOf + - SamAccountName - A property of type System.String, derived from the + directory attribute: sAMAccountName. This property is not supported + for AD LDS. + - SID - A property of type + System.Security.Principal.SecurityIdentifier, derived from the + directory attribute: objectSid + - SIDHistory - A property of type + System.Security.Principal.SecurityIdentifier, derived from the + directory attribute: sIDHistory. This property is not supported for + AD LDS. + - ADAccount - Represents a security account; that is, an Active + Directory object of type user, computer or iNetOrgPerson and is + derived from ADPrincipal. An ADAccount may contain the following + properties in addition to those inherited from its parent. + - AccountExpirationDate - A property of type System.DateTime, derived + from the directory attribute: accountExpires + - AccountLockoutTime - A property of type System.DateTime, derived + from the directory attribute: lockoutTime + - AccountNotDelegated - A property of type System.Boolean, derived + from the directory attributes: userAccountControl, + msDS-User-Account-Control-Computed. This property is not supported + by AD LDS. + - AllowReversiblePasswordEncryption - A property of type + System.Boolean, for AD DS it is derived from the directory + attribute: userAccountControl; for AD LDS it is derived from the + directory attribute: ms-DS-UserEncryptedTextPasswordAllowed + - BadLogonCount - A property of type System.Int32, derived from the + directory attribute: badPwdCount + - CannotChangePassword - A property of type System.Boolean, derived + from the directory attribute: nTSecurityDescriptor + - Certificates - A property of type + System.Security.Cryptography.X509Certificates.X509Certificate, + derived from the directory attribute: userCertificate + - DoesNotRequirePreAuth - A property of type System.Boolean, derived + from the directory attributes: userAccountControl, + msDS-User-Account-Control-Computed. This property is not supported + by AD LDS. + - Enabled - A property of type System.Boolean, for AD DS it is + derived from the directory attributes: userAccountControl, + msDS-User-Account-Control-Computed; for AD LDS it is derived from + the directory attribute msDS-UserAccountDisabled + - HomedirRequired - A property of type System.Boolean, derived from + the directory attributes: userAccountControl, + msDS-User-Account-Control-Computed. This property is not supported + by AD LDS. + - LastBadPasswordAttempt - A property of type System.DateTime, + derived from the directory attribute: badPasswordTime + - LastLogonDate - A property of type System.DateTime, derived from + the directory attribute: lastLogonTimestamp + - LockedOut - A property of type System.Boolean, for AD DS it is + derived from the directory attributes: userAccountControl, + msDS-User-Account-Control-Computed, lockoutTime; for AD LDS it is + derived from the directory attribute msDS-UserAccountDisabled + - MNSLogonAccount - A property of type System.Boolean, derived from + the directory attributes: userAccountControl, + msDS-User-Account-Control-Computed. This property is not supported + by AD LDS. + - PasswordExpired - A property of type System.Boolean, for AD DS it + is derived from the directory attributes: userAccountControl, + msDS-User-Account-Control-Computed; for AD LDS it is derived from + the directory attribute msDS-UserPasswordExpired + - PasswordLastSet - A property of type System.DateTime, derived from + the directory attribute: pwdLastSet + - PasswordNeverExpires - A property of type System.Boolean, for AD + LDS it is derived from the directory attributes: + userAccountControl, msDS-User-Account-Control-Computed; for AD LDS + it is derived from the directory attribute: + msDS-UserDontExpirePassword + - PasswordNotRequired - A property of type System.Boolean, for AD DS + it is derived from the directory attributes: userAccountControl, + msDS-User-Account-Control-Computed; for AD LDS it is derived from + the directory attribute: ms-DS-UserPasswordNotRequired + - PrimaryGroup - A property of type System.String, derived from the + directory attributes: primaryGroupID, objectSid. This property is + not supported by AD LDS. + - ServicePrincipalNames - A property of type System.String, derived + from the directory attribute: servicePrincipalName. This property + is not supported by AD LDS. + - TrustedForDelegation - A property of type System.Boolean, derived + from the directory attributes: userAccountControl, + msDS-User-Account-Control-Computed. This property is not supported + by AD LDS. + - TrustedToAuthForDelegation - A property of type System.Boolean, + derived from the directory attributes: userAccountControl, + msDS-User-Account-Control-Computed. This property is not supported + by AD LDS. + - UseDESKeyOnly - A property of type System.Boolean, derived from the + directory attributes: userAccountControl, + msDS-User-Account-Control-Computed. This property is not supported + by AD LDS. + - UserPrincipalName - A property of type System.String, derived from + the directory attribute: userPrincipalName + - ADComputer - Represents a computer and is derived from ADAccount. + An ADComputer may contain the following properties in addition to + those inherited from its parent. + - DNSHostName - A property of type System.String, derived from the + directory attribute: dNSHostName + - IPv4Address - A property of type System.String, derived from the + directory attribute: dNSHostName + - IPv6Address - A property of type System.String, derived from the + directory attribute: dNSHostName + - Location - A property of type System.String, derived from the + directory attribute: location + - ManagedBy - A property of type System.String, derived from the + directory attribute: managedBy + - OperatingSystem - A property of type System.String, derived from + the directory attribute: operatingSystem + - OperatingSystemHotfix - A property of type System.String, derived + from the directory attribute: operatingSystemHotfix + - OperatingSystemServicePack - A property of type System.String, + derived from the directory attribute: operatingSystemServicePack + - OperatingSystemVersion - A property of type System.String, + derived from the directory attribute: operatingSystemVersion + - ServiceAccount - A property of type System.String, derived from + the directory attribute: msDS-HostServiceAccount + - ADServiceAccount - Represents a managed service account; that is, + an Active Directory object of type msDS-ManagerdServiceAccount and + is derived from ADAccount. This class is not supported by AD LDS. + An ADServiceAccount may contain the following properties in + addition to those inherited from its parent. + - HostComputers - A property of type System.String, derived from + the directory attribute: msDS-HostServiceAccountBL + - ADUser - Represents a user (or iNetOrgPerson) and is derived from + ADAccount. An ADUser may contain the following properties in + addition to those inherited from its parent. + - City - A property of type System.String, derived from the + directory attribute: l + - Company - A property of type System.String, derived from the + directory attribute: company + - Country - A property of type System.String, derived from the + directory attribute: c + - Department - A property of type System.String, derived from the + directory attribute: department + - Division - A property of type System.String, derived from the + directory attribute: division + - EmailAddress - A property of type System.String, derived from the + directory attribute: mail + - EmployeeID - A property of type System.String, derived from the + directory attribute: employeeID + - EmployeeNumber - A property of type System.String, derived from + the directory attribute: employeeNumber + - Fax - A property of type System.String, derived from the + directory attribute: facsimileTelephoneNumber + - GivenName - A property of type System.String, derived from the + directory attribute: givenName + - HomeDirectory - A property of type System.String, derived from + the directory attribute: homeDirectory. This property is not + supported by AD LDS. + - HomeDrive - A property of type System.String, derived from the + directory attribute: homeDrive. This property is not supported by + AD LDS. + - HomePhone - A property of type System.String, derived from the + directory attribute: homePhone + - Initials - A property of type System.String, derived from the + directory attribute: initials + - LogonWorkstations - A property of type System.String, derived + from the directory attribute: userWorkstations. This property is + not supported by AD LDS. + - Manager - A property of type System.String, derived from the + directory attribute: manager + - MobilePhone - A property of type System.String, derived from the + directory attribute: mobile + - Office - A property of type System.String, derived from the + directory attribute: physicalDeliveryOfficeName + - OfficePhone - A property of type System.String, derived from the + directory attribute: telephoneNumber + - Organization - A property of type System.String, derived from the + directory attribute: o + - OtherName - A property of type System.String, derived from the + directory attribute: middleName + - POBox - A property of type System.String, derived from the + directory attribute: postOfficeBox + - PostalCode - A property of type System.String, derived from the + directory attribute: postalCode + - ProfilePath - A property of type System.String, derived from the + directory attribute: profilePath. This property is not supported + by AD LDS. + - ScriptPath - A property of type System.String, derived from the + directory attribute: scriptPath. This property is not supported + by AD LDS. + - SmartcardLogonRequired - A property of type System.Boolean, + derived from the directory attributes: userAccountControl, + msDS-User-Account-Control-Computed. This property is not + supported by AD LDS. + - State - A property of type System.String, derived from the + directory attribute: st + - StreetAddress - A property of type System.String, derived from + the directory attribute: streetAddress + - Surname - A property of type System.String, derived from the + directory attribute: sn + - Title - A property of type System.String, derived from the + directory attribute: title + - ADGroup -Represents a group and is derived from ADPrincipal. An + ADGroup may contain the following properties in addition to those + inherited from its parent. + - GroupCategory - A property of type + Microsoft.ActiveDirectory.Management.ADGroupCategory, derived from + the directory attribute: groupType + - GroupScope - A property of type + Microsoft.ActiveDirectory.Management.ADGroupScope, derived from the + directory attribute: groupType + - ManagedBy - A property of type System.String, derived from the + directory attribute: managedBy + - Members - A property of type System.String, derived from the + directory attribute: member + - ADDefaultDomainPasswordPolicy - Represents the domain-wide password policy + of an Active Directory domain and is derived from ADEntity. This class is + not supported by AD LDS. An ADDefaultDomainPasswordPolicy may contain the + following properties in addition to those inherited from its parent. + - ComplexityEnabled - A property of type System.Boolean, derived from the + directory attribute: pwdProperties + - DistinguishedName - A property of type System.String, derived from the + directory attribute: distinguishedName + - LockoutDuration - A property of type System.TimeSpan, derived from the + directory attribute: lockoutDuration + - LockoutObservationWindow - A property of type System.TimeSpan, derived + from the directory attribute: lockoutObservationWindow + - LockoutThreshold - A property of type System.Int32, derived from the + directory attribute: lockoutThreshold + - MaxPasswordAge - A property of type System.TimeSpan, derived from the + directory attribute: maxPwdAge + - MinPasswordAge - A property of type System.TimeSpan, derived from the + directory attribute: minPwdAge + - MinPasswordLength - A property of type System.Int32, derived from the + directory attribute: minPwdLength + - PasswordHistoryCount - A property of type System.Int32, derived from the + directory attribute: pwdHistoryLength + - ReversibleEncryptionEnabled - A property of type System.Boolean, derived + from the directory attribute: pwdProperties + - ADForest - Represents a Active Directory forest in AD DS or a Configuration + Set in AD LDS and is derived from ADEntity. This class is not supported by + AD LDS. An ADForest may contain the following properties in addition to + those inherited from its parent. + - ApplicationPartitions - A property of type System.String, derived from + the directory attribute: ApplicationPartitions + - CrossForestReferences - A property of type System.String, derived from + the directory attribute: CrossForestReferences + - DomainNamingMaster - A property of type System.String, derived from the + directory attribute: DomainNamingMaster + - Domains - A property of type System.String, derived from the directory + attribute: Domains + - ForestMode - A property of type System.Int32, derived from the directory + attribute: msDS-Behavior-Version + - GlobalCatalogs - A property of type System.String, derived from the + directory attribute: GlobalCatalogs + - Name - A property of type System.String, derived from the directory + attribute: name + - PartitionContainerName - A property of type System.String, derived from + the directory attribute: distinguishedName + - RootDomain - A property of type System.String, derived from the directory + attribute: RootDomain + - SchemaMaster - A property of type System.String, derived from the + directory attribute: SchemaMaster + - Sites - A property of type System.String, derived from the directory + attribute: Sites + - SPNSuffixes - A property of type System.String, derived from the + directory attribute: msDS-SPNSuffixes + - UPNSuffixes - A property of type System.String, derived from the + directory attribute: uPNSuffixes + - ADDirectoryServer - Represents a directory server used as either a domain + controller or an AD LDS instance and is derived from ADEntity. An + ADDirectoryServer may contain the following properties in addition to those + inherited from its parent. + - DefaultPartition - A property of type System.String, derived from the + directory attribute: DefaultPartition + - HostName - A property of type System.String, derived from the directory + attribute: HostName + - InvocationId - A property of type System.Guid, derived from the directory + attribute: InvocationId + - IPv4Address - A property of type System.String, derived from the + directory attribute: HostName + - IPv6Address - A property of type System.String, derived from the + directory attribute: HostName + - LdapPort - A property of type System.Int32, derived from the directory + attribute: LdapPort + - Name - A property of type System.String, derived from the directory + attribute: Name + - NTDSSettingsObjectDN - A property of type System.String, derived from the + directory attribute: NTDSSettingsObjectDN + - OperationMasterRoles - A property of type + Microsoft.ActiveDirectory.Management.ADOperationMasterRole, derived from + the directory attribute: OperationMasterRole + - Partitions - A property of type System.String, derived from the directory + attribute: Partitions + - ServerObjectDN - A property of type System.String, derived from the + directory attribute: ServerObjectDN + - ServerObjectGuid - A property of type System.Guid, derived from the + directory attribute: ServerObjectGuid + - Site - A property of type System.String, derived from the directory + attribute: Site + - SslPort - A property of type System.Int32, derived from the directory + attribute: SslPort + - ADDomainController - Represents a domain controller in AD DS and is + derived from ADDirectoryServer. An ADDomainController may contain the + following properties in addition to those inherited from its parent. + - ComputerObjectDN - A property of type System.String, derived from the + directory attribute: ComputerDN + - Domain - A property of type System.String, derived from the directory + attribute: Domain + - Enabled - A property of type System.Boolean, derived from the directory + attribute: Enabled + - Forest - A property of type System.String, derived from the directory + attribute: Forest + - IsGlobalCatalog - A property of type System.Boolean, derived from the + directory attribute: IsGlobalCatalog + - IsReadOnly - A property of type System.Boolean, derived from the + directory attribute: IsReadOnly + - OperatingSystem - A property of type System.String, derived from the + directory attribute: OSName + - OperatingSystemHotfix - A property of type System.String, derived from + the directory attribute: OSHotFix + - OperatingSystemServicePack - A property of type System.String, derived + from the directory attribute: OSServicepack + - OperatingSystemVersion - A property of type System.String, derived from + the directory attribute: OSVersion diff --git a/docset/winserver2022-ps/activedirectory/New-ADFineGrainedPasswordPolicy.md b/docset/winserver2022-ps/activedirectory/New-ADFineGrainedPasswordPolicy.md index 6517995ce1..6ccea5fdbf 100644 --- a/docset/winserver2022-ps/activedirectory/New-ADFineGrainedPasswordPolicy.md +++ b/docset/winserver2022-ps/activedirectory/New-ADFineGrainedPasswordPolicy.md @@ -71,13 +71,6 @@ PS C:\> New-ADFineGrainedPasswordPolicy -Instance $TemplatePSO -Name "AdminsPSO" This example creates two new fine-grained password policy objects using a template object. -### Example 3: Create a fine-grained password policy with manual account unlock -```powershell -PS C:\> New-ADFineGrainedPasswordPolicy -Name "ManualUnlockPSO" -Precedence 500 -ComplexityEnabled $true -Description "Manual Unlock Password Policy" -DisplayName "Manual Unlock PSO" -LockoutDuration "00:00:00" -LockoutObservationWindow "00:00:00" -LockoutThreshold 3 -``` - -This command creates a fine-grained password policy object named ManualUnlockPSO that would require manual unlock of accounts by the administrator. - ## PARAMETERS ### -AuthType @@ -275,6 +268,10 @@ The LDAP display name (**ldapDisplayName**) of this property is **msDS-lockoutOb The lockout observation window must be smaller than or equal to the lockout duration for a password policy. Use the *LockoutDuration* parameter to set the lockout duration time. +> [!NOTE] +> Setting the lockout observation window to 0 effectively means that the window is too short to +> observe more than one password attempt, therefore the account will never be locked out. + Specify the time interval in the following format: `D:H:M:S.F` diff --git a/docset/winserver2022-ps/clusterawareupdating/Add-CauClusterRole.md b/docset/winserver2022-ps/clusterawareupdating/Add-CauClusterRole.md index 0e8ae12be0..b3782210f1 100644 --- a/docset/winserver2022-ps/clusterawareupdating/Add-CauClusterRole.md +++ b/docset/winserver2022-ps/clusterawareupdating/Add-CauClusterRole.md @@ -11,7 +11,7 @@ title: Add-CauClusterRole # Add-CauClusterRole ## SYNOPSIS -Adds the CAU clustered role that provides the self-updating functionality to the specified cluster. +Adds the Cluster Aware Updating (CAU) clustered role that provides the self-updating functionality to the specified cluster. ## SYNTAX @@ -25,8 +25,10 @@ Add-CauClusterRole [-VirtualComputerObjectName ] [-GroupName ] [-PostUpdateScript ] [-ConfigurationName ] [-RequireAllNodesOnline] [-WarnAfter ] [-StopAfter ] [-RebootTimeoutMinutes ] [-SeparateReboots] [-RunPluginsSerially] [-StopOnPluginFailure] [-EnableFirewallRules] [-FailbackMode ] - [-SuspendClusterNodeTimeoutMinutes ] [[-ClusterName] ] [[-Credential] ] - [-Force] [-WhatIf] [-Confirm] [] + [-SuspendClusterNodeTimeoutMinutes ] [-ForcePauseNoDrain] [-ForcePauseAndDrain] + [-ForcePauseDrainAndReboot] [-SkipUpdateChecks] [-SiteAwareUpdatingOrder ] + [-OsRollingUpgrade] [-AttemptSoftReboot] [-RebootMode ] [[-ClusterName] ] + [[-Credential] ] [-Force] [-WhatIf] [-Confirm] [] ``` ### Weekly @@ -39,8 +41,25 @@ Add-CauClusterRole [-VirtualComputerObjectName ] [-GroupName ] [-PostUpdateScript ] [-ConfigurationName ] [-RequireAllNodesOnline] [-WarnAfter ] [-StopAfter ] [-RebootTimeoutMinutes ] [-SeparateReboots] [-RunPluginsSerially] [-StopOnPluginFailure] [-EnableFirewallRules] [-FailbackMode ] - [-SuspendClusterNodeTimeoutMinutes ] [[-ClusterName] ] [[-Credential] ] - [-Force] [-WhatIf] [-Confirm] [] + [-SuspendClusterNodeTimeoutMinutes ] [-ForcePauseNoDrain] [-ForcePauseAndDrain] + [-ForcePauseDrainAndReboot] [-SkipUpdateChecks] [-SiteAwareUpdatingOrder ] + [-OsRollingUpgrade] [-AttemptSoftReboot] [-RebootMode ] [[-ClusterName] ] + [[-Credential] ] [-Force] [-WhatIf] [-Confirm] [] +``` + +### Once + +``` +Add-CauClusterRole [-VirtualComputerObjectName ] [-GroupName ] [-RunOnce] + [-CauPluginName ] [-CauPluginArguments ] [-MaxFailedNodes ] + [-MaxRetriesPerNode ] [-NodeOrder ] [-PreUpdateScript ] + [-PostUpdateScript ] [-ConfigurationName ] [-RequireAllNodesOnline] + [-WarnAfter ] [-StopAfter ] [-RebootTimeoutMinutes ] [-SeparateReboots] + [-RunPluginsSerially] [-StopOnPluginFailure] [-EnableFirewallRules] [-FailbackMode ] + [-SuspendClusterNodeTimeoutMinutes ] [-ForcePauseNoDrain] [-ForcePauseAndDrain] + [-ForcePauseDrainAndReboot] [-SkipUpdateChecks] [-SiteAwareUpdatingOrder ] + [-OsRollingUpgrade] [-AttemptSoftReboot] [-RebootMode ] [[-ClusterName] ] + [[-Credential] ] [-Force] [-WhatIf] [-Confirm] [] ``` ## DESCRIPTION @@ -51,8 +70,8 @@ to a cluster, the failover cluster can update itself on the schedule that is spe without requiring an external computer to coordinate the cluster updating process. To run this cmdlet, Windows PowerShell® remoting must be enabled on each node. To do this, run the -`Enable-PSRemoting` cmdlet. In addition, ensure that the Windows Remote Management - Compatibility -Mode (HTTP-In) firewall exception is enabled on each node. +`Enable-PSRemoting` cmdlet. In addition, ensure that the **Windows Remote Management - Compatibility +Mode (HTTP-In)** firewall exception is enabled on each node. ## EXAMPLES @@ -75,14 +94,14 @@ $parameters = @{ Add-CauClusterRole @parameters ``` -This command adds the CAU clustered role, using a default name, on the cluster called CONTOSO-FC1. -The CAU clustered role is configured to perform Updating Runs on Tuesdays and Saturdays on the -second and fourth weeks of each month. In an Updating Run, the maximum number of failed nodes is two -and the maximum number of retries per node is two. A script called verifyupdatesinstalled.ps1 runs -on each node after it has been fully updated. Before an Updating Run can begin, all the nodes of -that cluster must be running. If it isn't already enabled, the Remote Shutdown Windows Firewall -rule group will be enabled on each cluster node. Because the command uses the **Force** parameter, the -cmdlet runs without displaying confirmation prompts. +This command adds the CAU clustered role, using a default name, on the cluster called +**CONTOSO-FC1**. The CAU clustered role is configured to perform Updating Runs on Tuesdays and +Saturdays on the second and fourth weeks of each month. In an Updating Run, the maximum number of +failed nodes is two and the maximum number of retries per node is two. A script called +`verifyupdatesinstalled.ps1` runs on each node after it has been fully updated. Before an Updating +Run can begin, all the nodes of that cluster must be running. If it isn't already enabled, the +Remote Shutdown Windows Firewall rule group will be enabled on each cluster node. Because the +command uses the **Force** parameter, the cmdlet runs without displaying confirmation prompts. This example uses splatting to pass parameter values from the `$parameters` variable to the command. Learn more about [Splatting](/powershell/module/microsoft.powershell.core/about/about_splatting). @@ -103,7 +122,7 @@ $parameters = @{ Add-CauClusterRole @parameters ``` -This command adds the CAU clustered role, using a default name, on the cluster called CONTOSO-FC1. +This command adds the CAU clustered role, using a default name, on the cluster called **CONTOSO-FC1**. The CAU clustered role is configured to perform Updating Runs on Tuesdays and Saturdays at an interval of every three weeks. In an Updating Run, the maximum number of failed nodes is two and the maximum number of retries per node is two. Updating Runs can begin even when the nodes of the @@ -131,7 +150,7 @@ $parameters = @{ Add-CauClusterRole @parameters ``` -This command adds the CAU clustered role, using a default name, on the cluster called CONTOSO-FC1. +This command adds the CAU clustered role, using a default name, on the cluster called **CONTOSO-FC1**. The CAU clustered role is configured to perform updates using the **Microsoft.WindowsUpdatePlugin** plug-in with the optional **IncludeRecommendedUpdates** parameter set to True, and using the **Microsoft.HotfixPlugin plug-in** using the hotfix root folder `\\CauHotfixSrv\shareName` and the @@ -146,21 +165,46 @@ Learn more about [Splatting](/powershell/module/microsoft.powershell.core/about/ ## PARAMETERS +### -AttemptSoftReboot + +Indicates that the CAU clustered role attempts a Kernel Soft Reboot (KSR) for the failover cluster. + +KSR bypasses BIOS/firmware initialization. You can only use KSR for updates that do not require a +BIOS/firmware initialization. + +```yaml +Type: SwitchParameter +Parameter Sets: DefaultParamSet +Aliases: + +Required: False +Position: Named +Default value: None +Accept pipeline input: False +Accept wildcard characters: False +``` + ### -CauPluginArguments -Specifies an array of name=value pairs (arguments) for each updating plug-in to use. -For instance, to specify a Domain argument for one plug-in: +Specifies a set of name=value pairs, as arguments, for each updating plug-in to use. + +For instance, to specify a Domain argument for one plug-in: + - `@{Domain=Domain.local}` -You can specify multiple pairs in a set separated with semicolons. -For instance: -- `@{name1=value1;name2=value2;name3=value3}` These name=value pairs must be meaningful to the - **CauPluginName** parameter that you specify. If you specify arguments for more than one plug-in, - provide the sets of name=value pairs in the order that you pass values in **CauPluginName**, - separated by commas. For instance: + +You can specify multiple pairs in a set separated with semicolons. For instance: + +- `@{name1=value1;name2=value2;name3=value3}` + +These name=value pairs must be meaningful to the **CauPluginName** parameter that you specify. If +you specify arguments for more than one plug-in, provide the sets of name=value pairs in the order +that you pass values in **CauPluginName**, separated by commas. For instance: + - `@{name1=value1;name2=value2;name3=value3},@{name4=value4;name5=value5}` -For the default **Microsoft.WindowsUpdatePlugin** plug-in, no arguments are needed. -The following arguments are optional: +For the default **Microsoft.WindowsUpdatePlugin** plug-in, no arguments are needed. The following +arguments are optional: + - **'IncludeRecommendedUpdates'='\'**: Boolean value to indicate that recommended updates will be applied in addition to important updates on each node. If not specified, the default value is False. @@ -168,35 +212,37 @@ The following arguments are optional: Agent to filter the updates that will be applied to each node. For a name, use **QueryString** and for a value, enclose the full query in quotation marks. If not specified, then the **Microsoft.WindowsUpdatePlugin** plug-in by default uses the following argument: -- `QueryString="IsInstalled=0 and Type='Software' and IsHidden=0 and IsAssigned=1"` For more - information about query strings for the default **Microsoft.WindowsUpdatePlugin** plug-in and the - criteria such as IsInstalled that can be included in the query strings, see - [IUpdateSearcher::Search method](https://go.microsoft.com/fwlink/p/?LinkId=223304). +- `QueryString="IsInstalled=0 and Type='Software' and IsHidden=0 and IsAssigned=1"` + +For more information about query strings for the default **Microsoft.WindowsUpdatePlugin** plug-in +and the criteria such as IsInstalled that can be included in the query strings, see +[IUpdateSearcher::Search method](/windows/win32/api/wuapi/nf-wuapi-iupdatesearcher-search). + +For the **Microsoft.HotfixPlugin** plug-in, the following argument is required: -For the **Microsoft.HotfixPlugin** plug-in. -the following argument is required: - **HotfixRootFolderPath=\**: The UNC path to a hotfix root folder in an SMB share with a - structure that contains the updates to apply and that contains the hotfix configuration file + structure that contains the updates to apply and that contains the hotfix configuration file. + +The following arguments are optional for the **Microsoft.HotfixPlugin** plug-in: -The following arguments are optional for the **Microsoft.HotfixPlugin** plug-in: - **RequireSmbEncryption=\**: Boolean value to indicate that SMB Encryption will be enforced for accessing data from the SMB share. If not specified, the default value is False. To ensure the integrity of the data accessed from the SMB share, the plug-in requires that the share is enabled for either SMB signing or SMB Encryption. -- **DisableAclChecks=\**: Boolean value to indicate that the plug-in checks for sufficient - permissions on the hotfix root folder and the hotfix configuration file. If not specified, the - default value is False. +- **DisableAclChecks=\**: Boolean value to indicate that the plug-in will check for + sufficient permissions on the hotfix root folder and the hotfix configuration file. If not + specified, the default value is False. - **HotfixInstallerTimeoutMinutes=\**: The length of time in minutes that the plug-in allows the hotfix installer process to return. If not specified, the default value is 30 minutes. - **HotfixConfigFileName=\**: Name for the hotfix configuration file. If not specified, the - default name DefaultHotfixConfigFile.xml is used. For more information about required and optional + default name `DefaultHotfixConfig.xml` is used. For more information about required and optional arguments for the **Microsoft.HotfixPlugin** plug-in, see - [How CAU Plug-ins Work](https://go.microsoft.com/fwlink/p/?LinkId=235333). + [How Cluster-Aware Updating plug-ins work](/windows-server/failover-clustering/cluster-aware-updating-plug-ins). ```yaml Type: Hashtable[] -Parameter Sets: (All) -Aliases: +Parameter Sets: MonthlyDayOfWeek, Weekly +Aliases: Required: False Position: Named @@ -208,16 +254,17 @@ Accept wildcard characters: False ### -CauPluginName Specifies one or more plug-ins to use when performing scans or updates. You can specify multiple -values separated with commas. The default is the Microsoft.WindowsUpdatePlugin plug-in. This plug-in -coordinates the Windows Update Agent software resident on each cluster node, the same software that -is used when updates are downloaded from Windows Update or Microsoft Update, or from a Windows -Server Update Services (WSUS) server. For more information about how plug-ins work with CAU, see -[How CAU Plug-ins Work](https://go.microsoft.com/fwlink/p/?LinkId=235333). +values separated with commas. The default is the **Microsoft.WindowsUpdatePlugin** plug-in. This +plug-in coordinates the Windows Update Agent software resident on each cluster node, the same +software that is used when updates are downloaded from Windows Update or Microsoft Update, or from +a Windows Server Update Services (WSUS) server. For more information about how plug-ins work with +CAU, see +[How CAU Plug-ins Work](/windows-server/failover-clustering/cluster-aware-updating-plug-ins). ```yaml Type: String[] -Parameter Sets: (All) -Aliases: +Parameter Sets: MonthlyDayOfWeek, Weekly +Aliases: Required: False Position: Named @@ -247,15 +294,15 @@ Accept wildcard characters: False ### -ConfigurationName Specifies the Windows PowerShell session configuration that defines the session in which scripts, -specified by the **PreUpdateScript** and **PostUpdateScript** parameters, and cmdlets are run, and can -limit the cmdlets that are available to be run. If either a pre-update or post-update script is -specified but a configuration name isn't specified, then the default session configuration that is -built into Windows PowerShell® is used. +specified by the **PreUpdateScript** and **PostUpdateScript** parameters, and cmdlets are run, and +can limit the cmdlets that are available to be run. If either a pre-update or post-update script is +specified but a configuration name is not specified, then the default session configuration that is +built into Windows PowerShell is used. ```yaml Type: String -Parameter Sets: (All) -Aliases: +Parameter Sets: MonthlyDayOfWeek, Weekly +Aliases: Required: False Position: Named @@ -264,22 +311,6 @@ Accept pipeline input: False Accept wildcard characters: False ``` -### -Confirm - -Prompts you for confirmation before running the cmdlet. - -```yaml -Type: SwitchParameter -Parameter Sets: (All) -Aliases: cf - -Required: False -Position: Named -Default value: False -Accept pipeline input: False -Accept wildcard characters: False -``` - ### -Credential Specifies the administrative credentials for the target cluster. @@ -303,18 +334,18 @@ Multiple values can be specified either separated with commas or as a hexadecima The acceptable values for this parameter are: -- **Sunday:** (0x01) -- **Monday:** (0x02) -- **Tuesday:** (0x04) -- **Wednesday:** (0x08) -- **Thursday:** (0x10) -- **Friday:** (0x20) -- **Saturday:** (0x40) +- `Sunday` or 0x01 +- `Monday` or 0x02 +- `Tuesday` or 0x04 +- `Wednesday` or 0x08 +- `Thursday` or 0x10 +- `Friday` or 0x20 +- `Saturday` or 0x40 ```yaml Type: Weekdays -Parameter Sets: (All) -Aliases: +Parameter Sets: MonthlyDayOfWeek, Weekly +Aliases: Accepted values: None, Sunday, Monday, Tuesday, Wednesday, Thursday, Friday, Saturday Required: False @@ -339,7 +370,7 @@ conflict with Group Policy settings that are configured for Windows Firewall. ```yaml Type: SwitchParameter Parameter Sets: (All) -Aliases: +Aliases: Required: False Position: Named @@ -356,16 +387,16 @@ another node. The acceptable values for this parameter are: -- NoFailback -- Immediate -- Policy +- `NoFailback` +- `Immediate` +- `Policy` -The default value is Immediate. +The default value is `Immediate`. ```yaml Type: FailbackType Parameter Sets: (All) -Aliases: +Aliases: Accepted values: NoFailback, Immediate, Policy Required: False @@ -391,6 +422,61 @@ Accept pipeline input: False Accept wildcard characters: False ``` +### -ForcePauseAndDrain + +Indicates that the CAU cluster role forces cluster nodes to pause and drain roles. + +A forced drain moves the roles off of the draining node even if the group cannot move. +A group might not be able to move because no other node can host the group or the group is locked. + +```yaml +Type: SwitchParameter +Parameter Sets: (All) +Aliases: + +Required: False +Position: Named +Default value: None +Accept pipeline input: False +Accept wildcard characters: False +``` + +### -ForcePauseDrainAndReboot + +Indicates that the CAU cluster role forces cluster nodes to pause, drain roles, and restart. + +A forced drain moves the roles off of the draining node even if the group cannot move. +A group might not be able to move because no other node can host the group or the group is locked. + +```yaml +Type: SwitchParameter +Parameter Sets: (All) +Aliases: + +Required: False +Position: Named +Default value: None +Accept pipeline input: False +Accept wildcard characters: False +``` + +### -ForcePauseNoDrain + +Indicates that the CAU cluster role forces cluster nodes to pause. +The nodes are not drained. + +```yaml +Type: SwitchParameter +Parameter Sets: (All) +Aliases: + +Required: False +Position: Named +Default value: None +Accept pipeline input: False +Accept wildcard characters: False +``` + ### -GroupName Specifies the NetBIOS name of the resource group for the CAU clustered role. @@ -398,7 +484,7 @@ Specifies the NetBIOS name of the resource group for the CAU clustered role. ```yaml Type: String Parameter Sets: (All) -Aliases: +Aliases: Required: False Position: Named @@ -435,7 +521,7 @@ The default for most clusters is approximately one-third of the number of nodes. ```yaml Type: Int32 Parameter Sets: (All) -Aliases: +Aliases: Required: False Position: Named @@ -454,7 +540,7 @@ The maximum is 64 and the default is 3. ```yaml Type: Int32 Parameter Sets: (All) -Aliases: +Aliases: Required: False Position: Named @@ -470,7 +556,23 @@ Specifies an array of cluster node names in the order that they should be update ```yaml Type: String[] Parameter Sets: (All) -Aliases: +Aliases: + +Required: False +Position: Named +Default value: None +Accept pipeline input: False +Accept wildcard characters: False +``` + +### -OsRollingUpgrade + +Indicates that the CAU cluster role upgrades the operating system of the cluster nodes without stopping the Hyper-V or the Scale-Out File Server workloads. + +```yaml +Type: SwitchParameter +Parameter Sets: MonthlyDayOfWeek, Weekly +Aliases: Required: False Position: Named @@ -489,8 +591,8 @@ available network share, to ensure that the script is always accessible to all t ```yaml Type: String -Parameter Sets: (All) -Aliases: +Parameter Sets: MonthlyDayOfWeek, Weekly +Aliases: Required: False Position: Named @@ -511,7 +613,31 @@ pre-update script fails, the node isn't updated. ```yaml Type: String Parameter Sets: (All) -Aliases: +Aliases: + +Required: False +Position: Named +Default value: None +Accept pipeline input: False +Accept wildcard characters: False +``` + +### -RebootMode + +Specifies the type of reboot to use for each node in the cluster during the update. The available +values are: + +- `ClusProp` +- `FullReboot` +- `SoftReboot` +- `PluginCustomReboot` +- `OrchestratorDefault` + +```yaml +Type: RebootType +Parameter Sets: (All) +Aliases: +Accepted values: ClusProp, FullReboot, SoftReboot, PluginCustomReboot, OrchestratorDefault Required: False Position: Named @@ -528,7 +654,7 @@ complete within this time, then the Updating Run on that node will be marked as ```yaml Type: Int32 Parameter Sets: (All) -Aliases: +Aliases: Required: False Position: Named @@ -545,7 +671,24 @@ begins. ```yaml Type: SwitchParameter Parameter Sets: (All) -Aliases: +Aliases: + +Required: False +Position: Named +Default value: None +Accept pipeline input: False +Accept wildcard characters: False +``` + +### -RunOnce + +Specifies that the CAU run should only be performed once, rather than on a recurring schedule. This +can be useful if you only need to perform a one-time update of your cluster nodes. + +```yaml +Type: SwitchParameter +Parameter Sets: Once +Aliases: Required: False Position: Named @@ -568,7 +711,7 @@ If a single plug-in is specified, a warning appears. ```yaml Type: SwitchParameter Parameter Sets: (All) -Aliases: +Aliases: Required: False Position: Named @@ -590,7 +733,41 @@ If a single plug-in is specified, a warning appears. ```yaml Type: SwitchParameter Parameter Sets: (All) -Aliases: +Aliases: + +Required: False +Position: Named +Default value: None +Accept pipeline input: False +Accept wildcard characters: False +``` + +### -SiteAwareUpdatingOrder + +Specifies the order in which the CAU cluster role updates cluster nodes. + +By default, CAU selects the order of nodes to update based on the level of activity. + +```yaml +Type: String[] +Parameter Sets: (All) +Aliases: + +Required: False +Position: Named +Default value: None +Accept pipeline input: False +Accept wildcard characters: False +``` + +### -SkipUpdateChecks + +Indicates that the CAU cluster role skips update checks. + +```yaml +Type: SwitchParameter +Parameter Sets: (All) +Aliases: Required: False Position: Named @@ -605,8 +782,8 @@ Specifies the earliest date on which the Updating Run can be triggered. ```yaml Type: DateTime -Parameter Sets: (All) -Aliases: +Parameter Sets: MonthlyDayOfWeek, Weekly +Aliases: Required: False Position: Named @@ -628,7 +805,7 @@ performing updates must be complete within this time limit. ```yaml Type: TimeSpan Parameter Sets: (All) -Aliases: +Aliases: Required: False Position: Named @@ -647,7 +824,7 @@ a warning appears. ```yaml Type: SwitchParameter Parameter Sets: (All) -Aliases: +Aliases: Required: False Position: Named @@ -671,7 +848,7 @@ for this value for every node in the cluster in the worst case. ```yaml Type: Int32 Parameter Sets: (All) -Aliases: +Aliases: Required: False Position: Named @@ -684,7 +861,7 @@ Accept wildcard characters: False Specifies the name of a pre-staged virtual computer object that is used by the CAU clustered role. For more information, see -[Steps to create computer objects in Active Directory](https://go.microsoft.com/fwlink/p/?LinkId=237624). +[Steps to create computer objects in Active Directory](/windows-server/failover-clustering/configure-ad-accounts). If not specified, then a virtual computer object is created using a generated name. Generating a name automatically requires the cluster name object to have permissions to create the virtual computer object in Active Directory. @@ -692,7 +869,7 @@ computer object in Active Directory. ```yaml Type: String Parameter Sets: (All) -Aliases: +Aliases: Required: False Position: Named @@ -710,7 +887,7 @@ regardless of the time taken by the Updating Run. ```yaml Type: TimeSpan Parameter Sets: (All) -Aliases: +Aliases: Required: False Position: Named @@ -736,6 +913,22 @@ Accept pipeline input: False Accept wildcard characters: False ``` +### -Confirm + +Prompts you for confirmation before running the cmdlet. + +```yaml +Type: SwitchParameter +Parameter Sets: (All) +Aliases: cf + +Required: False +Position: Named +Default value: False +Accept pipeline input: False +Accept wildcard characters: False +``` + ### -WhatIf Shows what would happen if the cmdlet runs. @@ -758,7 +951,7 @@ Accept wildcard characters: False This cmdlet supports the common parameters: -Debug, -ErrorAction, -ErrorVariable, -InformationAction, -InformationVariable, -OutVariable, -OutBuffer, -PipelineVariable, -Verbose, -WarningAction, and -WarningVariable. For more information, see -[about_CommonParameters](https://go.microsoft.com/fwlink/?LinkID=113216). +[about_CommonParameters](/powershell/module/microsoft.powershell.core/about/about_commonparameters). ## INPUTS @@ -766,19 +959,18 @@ This cmdlet supports the common parameters: -Debug, -ErrorAction, -ErrorVariable ## OUTPUTS -### None +### System.Object ## NOTES ## RELATED LINKS -[Disable-CauClusterRole](./Disable-CauClusterRole.md) - -[Enable-CauClusterRole](./Enable-CauClusterRole.md) +[Disable-CauClusterRole](disable-cauclusterrole.md) -[Get-CauClusterRole](./Get-CauClusterRole.md) +[Enable-CauClusterRole](enable-cauclusterrole.md) -[Remove-CauClusterRole](./Remove-CauClusterRole.md) +[Get-CauClusterRole](get-cauclusterrole.md) -[Set-CauClusterRole](./Set-CauClusterRole.md) +[Remove-CauClusterRole](remove-cauclusterrole.md) +[Set-CauClusterRole](set-cauclusterrole.md) diff --git a/docset/winserver2022-ps/clusterawareupdating/ClusterAwareUpdating.md b/docset/winserver2022-ps/clusterawareupdating/ClusterAwareUpdating.md index 365bc997f0..21cd1c8819 100644 --- a/docset/winserver2022-ps/clusterawareupdating/ClusterAwareUpdating.md +++ b/docset/winserver2022-ps/clusterawareupdating/ClusterAwareUpdating.md @@ -31,9 +31,11 @@ Exports one or more Updating Run reports into an HTML or CSV-formatted document. ### [Get-CauClusterRole](./Get-CauClusterRole.md) Gets configuration properties of the CAU clustered role on the specified cluster. -### [Get-CauPlugin](./Get-CauPlugin.md) -Gets information about one or more software updating plug-ins that are registered on the local -computer. +### [Get-CauDeviceInfoForFeatureUpdates](Get-CauDeviceInfoForFeatureUpdates.md) +Gets device information for feature updates to use with CAU. + +### [Get-CauPlugin](Get-CauPlugin.md) +Gets information about one or more software updating plug-ins that are registered on the local computer. ### [Get-CauReport](./Get-CauReport.md) Gets the Updating Run reports for all known Updating Runs, or all Updating Runs that match the @@ -70,5 +72,3 @@ Tests whether a cluster is properly set up to apply software updates using CAU. ### [Unregister-CauPlugin](./Unregister-CauPlugin.md) Removes a software updating plug-in from the list of plug-ins that are used by CAU. - - diff --git a/docset/winserver2022-ps/clusterawareupdating/Enable-CauClusterRole.md b/docset/winserver2022-ps/clusterawareupdating/Enable-CauClusterRole.md index c4cb36bb1b..6300b41950 100644 --- a/docset/winserver2022-ps/clusterawareupdating/Enable-CauClusterRole.md +++ b/docset/winserver2022-ps/clusterawareupdating/Enable-CauClusterRole.md @@ -34,9 +34,9 @@ cluster. The self-updating functionality of the cluster can be disabled with the Enable-CauClusterRole -ClusterName "CONTOSO-FC1" -Force ``` -This command enables the CAU clustered role on the CONTOSO-FC1 cluster to begin performing Updating -Runs. The cmdlet changes the status of the CAU clustered role to Running. Because the command -specified the **Force** parameter, the cmdlet runs without displaying confirmation prompts. +This command enables the CAU clustered role on the **CONTOSO-FC1** cluster to begin performing +Updating Runs. The cmdlet changes the status of the CAU clustered role to Running. The cmdlet runs +without displaying confirmation prompts, as the **Force** parameter was used. ## PARAMETERS @@ -58,28 +58,28 @@ Accept pipeline input: False Accept wildcard characters: False ``` -### -Confirm +### -Credential -Prompts you for confirmation before running the cmdlet. +Specifies the administrative credentials for the target cluster. ```yaml -Type: SwitchParameter +Type: PSCredential Parameter Sets: (All) -Aliases: cf +Aliases: Required: False Position: Named -Default value: False +Default value: None Accept pipeline input: False Accept wildcard characters: False ``` -### -Credential +### -Force -Specifies the administrative credentials for the target cluster. +Forces the command to run without asking for user confirmation. ```yaml -Type: PSCredential +Type: SwitchParameter Parameter Sets: (All) Aliases: @@ -90,26 +90,25 @@ Accept pipeline input: False Accept wildcard characters: False ``` -### -Force +### -Confirm -Forces the command to run without asking for user confirmation. +Prompts you for confirmation before running the cmdlet. ```yaml Type: SwitchParameter Parameter Sets: (All) -Aliases: +Aliases: cf Required: False Position: Named -Default value: None +Default value: False Accept pipeline input: False Accept wildcard characters: False ``` ### -WhatIf -Shows what would happen if the cmdlet runs. -The cmdlet isn't run. +Shows what would happen if the cmdlet runs. The cmdlet isn't run. ```yaml Type: SwitchParameter @@ -128,7 +127,7 @@ Accept wildcard characters: False This cmdlet supports the common parameters: -Debug, -ErrorAction, -ErrorVariable, -InformationAction, -InformationVariable, -OutVariable, -OutBuffer, -PipelineVariable, -Verbose, -WarningAction, and -WarningVariable. For more information, see -[about_CommonParameters](https://go.microsoft.com/fwlink/?LinkID=113216). +[about_CommonParameters](/powershell/module/microsoft.powershell.core/about/about_commonparameters). ## INPUTS @@ -136,19 +135,18 @@ This cmdlet supports the common parameters: -Debug, -ErrorAction, -ErrorVariable ## OUTPUTS -### None +### System.Object ## NOTES ## RELATED LINKS -[Add-CauClusterRole](./Add-CauClusterRole.md) - -[Disable-CauClusterRole](./Disable-CauClusterRole.md) +[Add-CauClusterRole](add-cauclusterrole.md) -[Get-CauClusterRole](./Get-CauClusterRole.md) +[Disable-CauClusterRole](disable-cauclusterrole.md) -[Remove-CauClusterRole](./Remove-CauClusterRole.md) +[Get-CauClusterRole](get-cauclusterrole.md) -[Set-CauClusterRole](./Set-CauClusterRole.md) +[Remove-CauClusterRole](remove-cauclusterrole.md) +[Set-CauClusterRole](set-cauclusterrole.md) diff --git a/docset/winserver2022-ps/clusterawareupdating/Get-CauDeviceInfoForFeatureUpdates.md b/docset/winserver2022-ps/clusterawareupdating/Get-CauDeviceInfoForFeatureUpdates.md new file mode 100644 index 0000000000..fffdccf441 --- /dev/null +++ b/docset/winserver2022-ps/clusterawareupdating/Get-CauDeviceInfoForFeatureUpdates.md @@ -0,0 +1,121 @@ +--- +description: The Get-CauDeviceInfoForFeatureUpdates cmdlet gets device information for feature updates to use with Cluster-Aware Updating (CAU). +external help file: ClusterAwareUpdating.dll-Help.xml +Module Name: ClusterAwareUpdating +ms.date: 09/17/2021 +online version: https://docs.microsoft.com/powershell/module/clusterawareupdating/get-caudeviceinfoforfeatureupdates?view=windowsserver2022-ps&wt.mc_id=ps-gethelp +schema: 2.0.0 +title: Get-CauDeviceInfoForFeatureUpdates +--- + +# Get-CauDeviceInfoForFeatureUpdates + +## SYNOPSIS +Gets device information for feature updates to use with CAU. + +## SYNTAX + +``` +Get-CauDeviceInfoForFeatureUpdates [[-ClusterName] ] [-Credential ] + -PathToDirectory [] +``` + +## DESCRIPTION + +The `Get-CauDeviceInfoForFeatureUpdates` cmdlet gets device information for feature updates to use +with Cluster-Aware Updating (CAU). + +## EXAMPLES + +### Example 1: Get device information + +```powershell +$Parameters = @{ + ClusterName = 'CONTOSO-FC1' + PathToDirectory = 'C:\temp\contoso-device-info' +} +Get-CauDeviceInfoForFeatureUpdates $Parameters +``` + +This example gets device information for CAU for the specified cluster. This example uses +splatting to pass parameter values from the `$Parameters` variable to the command. Learn more about +[Splatting](/powershell/module/microsoft.powershell.core/about/about_splatting). + +## PARAMETERS + +### -ClusterName + +Specifies the name of the cluster fow which to get device information. + +```yaml +Type: String +Parameter Sets: (All) +Aliases: + +Required: False +Position: 0 +Default value: None +Accept pipeline input: False +Accept wildcard characters: False +``` + +### -Credential + +Specifies the administrative credentials for the target cluster. + +```yaml +Type: PSCredential +Parameter Sets: (All) +Aliases: + +Required: False +Position: Named +Default value: None +Accept pipeline input: False +Accept wildcard characters: False +``` + +### -PathToDirectory + +Specifies a directory. + +```yaml +Type: String +Parameter Sets: (All) +Aliases: + +Required: True +Position: Named +Default value: None +Accept pipeline input: False +Accept wildcard characters: False +``` + +### CommonParameters + +This cmdlet supports the common parameters: -Debug, -ErrorAction, -ErrorVariable, +-InformationAction, -InformationVariable, -OutVariable, -OutBuffer, -PipelineVariable, -Verbose, +-WarningAction, and -WarningVariable. For more information, see +[about_CommonParameters](/powershell/module/microsoft.powershell.core/about/about_commonparameters). + +## INPUTS + +### None + +## OUTPUTS + +### System.String + +### Microsoft.ClusterAwareUpdating.ActivityIdMap + +## NOTES + +## RELATED LINKS + +[Get-CauClusterRole](get-cauclusterrole.md) + +[Get-CauPlugin](get-cauplugin.md) + +[Get-CauReport](get-caureport.md) + +[Get-CauRun](get-caurun.md) diff --git a/docset/winserver2022-ps/clusterawareupdating/Get-CauReport.md b/docset/winserver2022-ps/clusterawareupdating/Get-CauReport.md index 7596f4fc77..e0b02d78a6 100644 --- a/docset/winserver2022-ps/clusterawareupdating/Get-CauReport.md +++ b/docset/winserver2022-ps/clusterawareupdating/Get-CauReport.md @@ -19,38 +19,40 @@ specified dates or other specified parameters. ### AllParamsSet (Default) ``` -Get-CauReport [[-ClusterName] ] [-Detailed] [-Credential ] [] +Get-CauReport [[-ClusterName] ] [-Detailed] [-Credential ] + [] ``` ### RangeParamSet ``` -Get-CauReport [[-ClusterName] ] [[-StartDate] ] [[-EndDate] ] [-Detailed] - [-Credential ] [] +Get-CauReport [[-ClusterName] ] [[-StartDate] ] [[-EndDate] ] + [-Detailed] [-Credential ] [] ``` ### LastParamSet ``` -Get-CauReport [[-ClusterName] ] [-Last] [-Detailed] [-Credential ] [] +Get-CauReport [[-ClusterName] ] [-Last] [-Detailed] [-Credential ] + [] ``` ### SpecificReportParamSet ``` -Get-CauReport [[-ClusterName] ] [-Report ] [-Credential ] - [] +Get-CauReport [[-ClusterName] ] [-Report ] + [-Credential ] [] ``` ## DESCRIPTION The `Get-CauReport` cmdlet gets the Updating Run reports for all known Updating Runs, or all Updating Runs that match the specified dates or other specified parameters. This cmdlet can return a -list of all Updating Run reports between the specified **StartDate** and **EndDate** parameters, or if -the **Last** parameter is specified instead of dates, then the cmdlet returns the most recent Updating -Run report. By default, the report contains summaries only, but more detail can be obtained with the -**Detailed** parameter or by using the **Report** parameter and specifying a Cluster-Aware Updating -(CAU) report summary object. +list of all Updating Run reports between the specified **StartDate** and **EndDate** parameters, or +if the **Last** parameter is specified instead of dates, then the cmdlet returns the most recent +Updating Run report. By default, the report contains summaries only, but more detail can be obtained +with the **Detailed** parameter or by using the **Report** parameter and specifying a Cluster-Aware +Updating (CAU) report summary object. ## EXAMPLES @@ -60,8 +62,8 @@ Run report. By default, the report contains summaries only, but more detail can Get-CauReport -ClusterName Contoso-FC1 -StartDate 01/01/2012 -Detailed ``` -This command gets a detailed list of the updating runs performed on the cluster named Contoso-FC1 on -01/01/2012 or later. +This command gets a detailed list of the updating runs performed on the cluster named **Contoso-FC1** +on 01/01/2012 or later. ### Example 2: Get a detailed list of updating runs from a date span from the specified cluster @@ -69,7 +71,7 @@ This command gets a detailed list of the updating runs performed on the cluster Get-CauReport -ClusterName "Contoso-FC1" -StartDate 01/01/2012 -EndDate 04/01/2012 -Detailed ``` -This command gets a detailed list of the updating runs performed on the cluster called Contoso-FC1 +This command gets a detailed list of the updating runs performed on the cluster called **Contoso-FC1** starting with updating runs on 01/01/2012 and ending with updating runs on 04/01/2012. ### Example 3: Get the last updating run summary from the specified cluster @@ -79,7 +81,7 @@ $CauReportSummary = Get-CauReport "Contoso-FC1" -Last Get-CauReport "Contoso-FC1" -Report $CauReportSummary ``` -The first command gets the last updating run report summary from the cluster named Contoso-FC1 and +The first command gets the last updating run report summary from the cluster named **Contoso-FC1** and stores the result in the variable named `$CauReportSummary`. The second command gets the detailed report from the information stored in the `$CauReportSummary` @@ -206,7 +208,7 @@ Accept wildcard characters: False This cmdlet supports the common parameters: -Debug, -ErrorAction, -ErrorVariable, -InformationAction, -InformationVariable, -OutVariable, -OutBuffer, -PipelineVariable, -Verbose, -WarningAction, and -WarningVariable. For more information, see -[about_CommonParameters](https://go.microsoft.com/fwlink/?LinkID=113216). +[about_CommonParameters](/powershell/module/microsoft.powershell.core/about/about_commonparameters). ## INPUTS @@ -222,5 +224,4 @@ This cmdlet supports the common parameters: -Debug, -ErrorAction, -ErrorVariable ## RELATED LINKS -[Export-CauReport](./Export-CauReport.md) - +[Export-CauReport](export-caureport.md) diff --git a/docset/winserver2022-ps/clusterawareupdating/Invoke-CauRun.md b/docset/winserver2022-ps/clusterawareupdating/Invoke-CauRun.md index 972c4c784d..814b4739b9 100644 --- a/docset/winserver2022-ps/clusterawareupdating/Invoke-CauRun.md +++ b/docset/winserver2022-ps/clusterawareupdating/Invoke-CauRun.md @@ -22,17 +22,19 @@ Invoke-CauRun [-MaxFailedNodes ] [-MaxRetriesPerNode ] [-NodeOrder [-PreUpdateScript ] [-PostUpdateScript ] [-ConfigurationName ] [-RequireAllNodesOnline] [-WarnAfter ] [-StopAfter ] [-RebootTimeoutMinutes ] [-SeparateReboots] [-EnableFirewallRules] - [-FailbackMode ] [-SuspendClusterNodeTimeoutMinutes ] [-Force] [[-ClusterName] -] [[-CauPluginName] ] [[-Credential] ] - [-CauPluginArguments ] [-RunPluginsSerially] [-StopOnPluginFailure] [-WhatIf] - [-Confirm] [] + [-FailbackMode ] [-SuspendClusterNodeTimeoutMinutes ] [-Force] + [-ForcePauseNoDrain] [-ForcePauseAndDrain] [-ForcePauseDrainAndReboot] [-SkipUpdateChecks] + [-ForceSelfUpdate] [-SiteAwareUpdatingOrder ] [[-ClusterName] ] + [[-CauPluginName] ] [[-Credential] ] [-CauPluginArguments ] [-RunPluginsSerially] [-StopOnPluginFailure] [-OsRollingUpgrade] [-AttemptSoftReboot] + [-RebootMode ] [-WhatIf] [-Confirm] [] ``` ### RecoverParamSet ``` -Invoke-CauRun [-ForceRecovery] [-Force] [[-ClusterName] ] [[-Credential] ] - [-WhatIf] [-Confirm] [] +Invoke-CauRun [-ForceRecovery] [-Force] [-ForcePauseNoDrain] [-ForcePauseAndDrain] + [-ForcePauseDrainAndReboot] [-SkipUpdateChecks] [-ForceSelfUpdate] [[-ClusterName] ] + [[-Credential] ] [-WhatIf] [-Confirm] [] ``` ## DESCRIPTION @@ -40,18 +42,19 @@ Invoke-CauRun [-ForceRecovery] [-Force] [[-ClusterName] ] [[-Credential] The `Invoke-CauRun` cmdlet performs a scan of cluster nodes for applicable updates and installs those updates through an updating run on the specified cluster. The updating run process includes the following: -- Scanning for and downloading applicable updates on each cluster node. -- Moving currently running clustered roles off each cluster node. -- Installing the updates on each cluster node. -- Restarting cluster nodes if required by the installed updates. -- Moving the clustered roles back to the original nodes. + +- Scanning for and downloading applicable updates on each cluster node. +- Moving currently running clustered roles off each cluster node. +- Installing the updates on each cluster node. +- Restarting cluster nodes if required by the installed updates. +- Moving the clustered roles back to the original nodes. - The updating run process also includes ensuring that quorum is maintained, checking for additional updates that can only be installed after the initial set of updates are installed, and saving a report of the actions taken. -To run this cmdlet with the **PostUpdateScript** or **PreUpdateScript** parameter, Windows PowerShell -remoting must be enabled on each node. To do this, run the `Enable-PSRemoting` cmdlet. In -addition, ensure that the **Windows Remote Management - Compatibility Mode (HTTP-In)** firewall +To run this cmdlet with the **PostUpdateScript** or **PreUpdateScript** parameter, Windows +PowerShell remoting must be enabled on each node. To do this, run the `Enable-PSRemoting` cmdlet. +In addition, ensure that the **Windows Remote Management - Compatibility Mode (HTTP-In)** firewall exception is enabled on each node. ## EXAMPLES @@ -70,12 +73,12 @@ $parameters = @{ Invoke-CauRun @parameters ``` -This command performs a scan and a full updating run on the cluster named CONTOSO-FC1. This cmdlet -uses the **Microsoft.WindowsUpdatePlugin** plug-in and requires that all cluster nodes be online -before the running this cmdlet. In addition, this cmdlet allows no more than three retries per node -before marking the node as failed, and allows no more than one node to fail before marking the -entire updating run as failed. Because the command specifies the **Force** parameter, the cmdlet runs -without displaying confirmation prompts. +This command performs a scan and a full updating run on the cluster named `CONTOSO-FC1`. This +cmdlet uses the **Microsoft.WindowsUpdatePlugin** plug-in and requires that all cluster nodes be +online before the running this cmdlet. In addition, this cmdlet allows no more than three retries +per node before marking the node as failed, and allows no more than one node to fail before marking +the entire updating run as failed. Because the command specifies the **Force** parameter, the +cmdlet runs without displaying confirmation prompts. This example uses splatting to pass parameter values from the `$parameters` variable to the command. Learn more about [Splatting](/powershell/module/microsoft.powershell.core/about/about_splatting). @@ -97,7 +100,7 @@ $parameters = @{ Invoke-CauRun @parameters ``` -This command performs a scan and a full updating run on the cluster named CONTOSO-FC1. This cmdlet +This command performs a scan and a full updating run on the cluster named **CONTOSO-FC1**. This cmdlet uses the **Microsoft.WindowsUpdatePlugin** plug-in with the default configuration, and the **Microsoft.HotfixPlugin** plug-in using the hotfix root folder `\\CauHotfixSrv\shareName` and the default hotfix configuration file. If it isn't already enabled, the **Remote Shutdown** Windows @@ -118,57 +121,84 @@ Invoke-CauRun -ClusterName "CONTOSO-FC1"-ForceRecovery -Force ``` This command recovers from a previous updating run that failed and left the cluster in a Locked -state for the cluster named CONTOSO-FC1. Because the command specifies the **Force** parameter, the -recovery is performed without confirmation prompts. +state for the cluster named **CONTOSO-FC1**. Because the command specifies the **Force** parameter, +the recovery is performed without confirmation prompts. ## PARAMETERS +### -AttemptSoftReboot + +Indicates that command attempts a Kernel Soft Reboot (KSR) for the failover cluster. + +KSR bypasses BIOS/firmware initialization. +You can only use KSR for updates that do not require a BIOS/firmware initialization. + +```yaml +Type: SwitchParameter +Parameter Sets: DefaultParamSet +Aliases: + +Required: False +Position: Named +Default value: None +Accept pipeline input: False +Accept wildcard characters: False +``` + ### -CauPluginArguments -Specifies a set of name=value pairs for each updating plug-in to use. -For instance, to specify a Domain argument for one plug-in: +Specifies a set of name=value pairs, as arguments, for each updating plug-in to use. + +For instance, to specify a Domain argument for one plug-in: + - `@{Domain=Domain.local}` -You can specify multiple pairs in a set separated with semicolons. -For instance: -- `@{name1=value1;name2=value2;name3=value3}` These name=value pairs must be meaningful to the - **CauPluginName** that you specify. If you specify arguments for more than one plug-in, provide - the sets of name=value pairs in the order that you pass values in **CauPluginName**, separated by - commas. For instance: + +You can specify multiple pairs in a set separated with semicolons. For instance: + +- `@{name1=value1;name2=value2;name3=value3}` + +These name=value pairs must be meaningful to the **CauPluginName** parameter that you specify. If +you specify arguments for more than one plug-in, provide the sets of name=value pairs in the order +that you pass values in **CauPluginName**, separated by commas. For instance: + - `@{name1=value1;name2=value2;name3=value3},@{name4=value4;name5=value5}` -For the default **Microsoft.WindowsUpdatePlugin** plug-in, no arguments are needed. -The following arguments are optional: -- **'IncludeRecommendedUpdates'='\'**: Boolean value to indicate that recommended updates will be applied in addition to important updates on each node. -If not specified, the default value is **'False'**. --- A standard Windows Update Agent query string that specifies criteria used by the Windows Update -Agent to filter the updates that will be applied to each node. For a name, use **QueryString** and -for a value, enclose the full query in quotation marks. If not specified, then the -**Microsoft.WindowsUpdatePlugin** plug-in by default uses the following argument: +For the default **Microsoft.WindowsUpdatePlugin** plug-in, no arguments are needed. The following +arguments are optional: + +- **'IncludeRecommendedUpdates'='\'**: Boolean value to indicate that recommended updates + will be applied in addition to important updates on each node. If not specified, the default value + is False. +- A standard Windows Update Agent query string that specifies criteria used by the Windows Update + Agent to filter the updates that will be applied to each node. For a name, use **QueryString** and + for a value, enclose the full query in quotation marks. If not specified, then the + **Microsoft.WindowsUpdatePlugin** plug-in by default uses the following argument: - `QueryString="IsInstalled=0 and Type='Software' and IsHidden=0 and IsAssigned=1"` For more information about query strings for the default **Microsoft.WindowsUpdatePlugin** plug-in and the criteria such as IsInstalled that can be included in the query strings, see -[IUpdateSearcher::Search method](https://go.microsoft.com/fwlink/p/?LinkId=223304). +[IUpdateSearcher::Search method](/windows/win32/api/wuapi/nf-wuapi-iupdatesearcher-search). + +For the **Microsoft.HotfixPlugin** plug-in, the following argument is required: -For the **Microsoft.HotfixPlugin** plug-in, the following argument is required: -- **HotfixRootFolderPath**: The UNC path to a hotfix root folder in an SMB share with a structure - that contains the updates to apply and that contains the hotfix configuration file. +- **HotfixRootFolderPath=\**: The UNC path to a hotfix root folder in an SMB share with a + structure that contains the updates to apply and that contains the hotfix configuration file. -The following arguments are optional for the **Microsoft.HotfixPlugin** plug-in: -- **RequireSmbEncryption=\**: Boolean value to indicate that SMB Encryption is enforced for - data accessed from the SMB share. If not specified, the default value is False. To ensure the +The following arguments are optional for the **Microsoft.HotfixPlugin** plug-in: + +- **RequireSmbEncryption=\**: Boolean value to indicate that SMB Encryption will be enforced + for accessing data from the SMB share. If not specified, the default value is False. To ensure the integrity of the data accessed from the SMB share, the plug-in requires that the share is enabled for either SMB signing or SMB Encryption. -- **DisableAclChecks=\**: Boolean value to indicate that the plug-in checks for sufficient - permissions on the hotfix root folder and the hotfix configuration file. If not specified, the - default value is False. +- **DisableAclChecks=\**: Boolean value to indicate that the plug-in will check for + sufficient permissions on the hotfix root folder and the hotfix configuration file. If not + specified, the default value is False. - **HotfixInstallerTimeoutMinutes=\**: The length of time in minutes that the plug-in allows the hotfix installer process to return. If not specified, the default value is 30 minutes. -- **HotfixConfigFileName=\**: Name for the hotfix configuration file. -If not specified, the default name DefaultHotfixConfig.xml is used. - -For more information about required and optional arguments for the **Microsoft.HotfixPlugin** -plug-in, see [How CAU Plug-ins Work](https://go.microsoft.com/fwlink/p/?LinkId=235333). +- **HotfixConfigFileName=\**: Name for the hotfix configuration file. If not specified, the + default name `DefaultHotfixConfig.xml` is used. For more information about required and optional + arguments for the **Microsoft.HotfixPlugin** plug-in, see + [How Cluster-Aware Updating plug-ins work](/windows-server/failover-clustering/cluster-aware-updating-plug-ins). ```yaml Type: Hashtable[] @@ -189,7 +219,7 @@ separated with commas. The default is the **Microsoft.WindowsUpdatePlugin** plug coordinates the Windows Update Agent software resident on each cluster node, the same software that is used when updates are downloaded from Windows Update or Microsoft Update, or from a Windows Server Update Services (WSUS) server. For more information about how plug-ins work with CAU, see -[How CAU Plug-ins Work](https://go.microsoft.com/fwlink/p/?LinkId=235333). +[How CAU Plug-ins Work](/windows-server/failover-clustering/cluster-aware-updating-plug-ins). ```yaml Type: String[] @@ -301,9 +331,9 @@ Specifies the method used to bring drained workloads back to the node, at the en node. Drained workloads are workloads that were previously run on the node, but were moved to another node. The acceptable values for this parameter are: -- NoFailback -- Immediate -- Policy +- `NoFailback` +- `Immediate` +- `Policy` The default value is Immediate. @@ -336,6 +366,61 @@ Accept pipeline input: False Accept wildcard characters: False ``` +### -ForcePauseAndDrain + +Indicates that the command forces cluster nodes to pause and drain roles. + +A forced drain moves the roles off of the draining node even if the group cannot move. +A group might not be able to move because no other node can host the group or the group is locked. + +```yaml +Type: SwitchParameter +Parameter Sets: (All) +Aliases: + +Required: False +Position: Named +Default value: None +Accept pipeline input: False +Accept wildcard characters: False +``` + +### -ForcePauseDrainAndReboot + +Indicates that the command forces cluster nodes to pause, drain roles, and restart. + +A forced drain moves the roles off of the draining node even if the group cannot move. +A group might not be able to move because no other node can host the group or the group is locked. + +```yaml +Type: SwitchParameter +Parameter Sets: (All) +Aliases: + +Required: False +Position: Named +Default value: None +Accept pipeline input: False +Accept wildcard characters: False +``` + +### -ForcePauseNoDrain + +Indicates that the command forces cluster nodes to pause. +The nodes are not drained. + +```yaml +Type: SwitchParameter +Parameter Sets: (All) +Aliases: + +Required: False +Position: Named +Default value: None +Accept pipeline input: False +Accept wildcard characters: False +``` + ### -ForceRecovery Indicates that the cmdlet recovers from a previous failed run that left the cluster in a Locked @@ -356,6 +441,22 @@ Accept pipeline input: False Accept wildcard characters: False ``` +### -ForceSelfUpdate + +Specifies whether to update the CAU plugin on the local computer before running the update. + +```yaml +Type: SwitchParameter +Parameter Sets: (All) +Aliases: + +Required: False +Position: Named +Default value: None +Accept pipeline input: False +Accept wildcard characters: False +``` + ### -MaxFailedNodes Specifies the maximum number of nodes on which updating can fail. @@ -399,6 +500,23 @@ Specifies an array of cluster nodes names in the order that they are updated. ```yaml Type: String[] Parameter Sets: DefaultParamSet +Aliases: + +Required: False +Position: Named +Default value: None +Accept pipeline input: False +Accept wildcard characters: False +``` + +### -OsRollingUpgrade + +Indicates that the CAU cluster role upgrades the operating system of the cluster nodes without +stopping the Hyper-V or the Scale-Out File Server workloads. + +```yaml +Type: SwitchParameter +Parameter Sets: DefaultParamSet Aliases: Required: False @@ -431,7 +549,7 @@ Accept wildcard characters: False ### -PreUpdateScript Specifies the path and file name for a Windows PowerShell script to run on each node before updating -begins, and before the node is put into Maintenance mode. The file name extension must be .ps1 and +begins, and before the node is put into Maintenance mode. The file name extension must be `.ps1` and the total length of the path plus the file name must be no longer than 260 characters. As a best practice, the script should be located on a disk in cluster storage, or at a highly available network share, to ensure that the script is always accessible to all the cluster nodes. If a @@ -449,6 +567,30 @@ Accept pipeline input: False Accept wildcard characters: False ``` +### -RebootMode + +Specifies the type of reboot to use for each node in the cluster during the update. The available +values are: + +- `ClusProp` +- `FullReboot` +- `SoftReboot` +- `PluginCustomReboot` +- `OrchestratorDefault` + +```yaml +Type: RebootType +Parameter Sets: DefaultParamSet +Aliases: +Accepted values: ClusProp, FullReboot, SoftReboot, PluginCustomReboot, OrchestratorDefault + +Required: False +Position: Named +Default value: None +Accept pipeline input: False +Accept wildcard characters: False +``` + ### -RebootTimeoutMinutes Specifies the time in minutes that CAU allows for the restarting of a node. If the restart doesn't @@ -490,8 +632,8 @@ used during an updating run. By default, CAU scans and stages the applicable upd plug-ins in parallel. Regardless of the configuration of this parameter, CAU installs the applicable updates for each plug-in sequentially. -The parameter is valid only when multiple plug-ins are specified for the **CauPluginName** parameter. -If a single plug-in is specified, a warning appears. +The parameter is valid only when multiple plug-ins are specified for the **CauPluginName** +parameter. If a single plug-in is specified, a warning appears. ```yaml Type: SwitchParameter @@ -512,8 +654,8 @@ the node, if the installation of an update by a plug-in requires a restart when are used during an updating run. By default, during an updating run, all plug-ins complete the installation of updates on a cluster node before the node restarts one time. -The parameter is valid only when multiple plug-ins are specified for the **CauPluginName** parameter. -If a single plug-in is specified, a warning appears. +The parameter is valid only when multiple plug-ins are specified for the **CauPluginName** +parameter. If a single plug-in is specified, a warning appears. ```yaml Type: SwitchParameter @@ -527,6 +669,40 @@ Accept pipeline input: False Accept wildcard characters: False ``` +### -SiteAwareUpdatingOrder + +Specifies the order in which the command updates cluster nodes. + +By default, CAU selects the order of nodes to update based on the level of activity. + +```yaml +Type: String[] +Parameter Sets: DefaultParamSet +Aliases: + +Required: False +Position: Named +Default value: None +Accept pipeline input: False +Accept wildcard characters: False +``` + +### -SkipUpdateChecks + +Indicates that the command skips update checks. + +```yaml +Type: SwitchParameter +Parameter Sets: (All) +Aliases: + +Required: False +Position: Named +Default value: None +Accept pipeline input: False +Accept wildcard characters: False +``` + ### -StopAfter Specifies the time in minutes after which the updating run is canceled if it hasn't completed. The @@ -556,8 +732,8 @@ subsequent updates on the node that are coordinated by the remaining plug-ins ar multiple plug-ins are used during an updating run. By default, a failure by one plug-in doesn't affect the application of updates on a node by other plug-ins. -The parameter is valid only when multiple plug-ins are specified for the **CauPluginName** parameter. -If a single plug-in is specified, a warning appears. +The parameter is valid only when multiple plug-ins are specified for the **CauPluginName** +parameter. If a single plug-in is specified, a warning appears. ```yaml Type: SwitchParameter @@ -616,8 +792,7 @@ Accept wildcard characters: False ### -WhatIf -Shows what would happen if the cmdlet runs. -The cmdlet isn't run. +Shows what would happen if the cmdlet runs. The cmdlet isn't run. ```yaml Type: SwitchParameter @@ -636,7 +811,7 @@ Accept wildcard characters: False This cmdlet supports the common parameters: -Debug, -ErrorAction, -ErrorVariable, -InformationAction, -InformationVariable, -OutVariable, -OutBuffer, -PipelineVariable, -Verbose, -WarningAction, and -WarningVariable. For more information, see -[about_CommonParameters](https://go.microsoft.com/fwlink/?LinkID=113216). +[about_CommonParameters](/powershell/module/microsoft.powershell.core/about/about_commonparameters). ## INPUTS @@ -662,9 +837,10 @@ This cmdlet supports the common parameters: -Debug, -ErrorAction, -ErrorVariable ## RELATED LINKS -[Add-CauClusterRole](./Add-CauClusterRole.md) +[Add-CauClusterRole](add-cauclusterrole.md) -[Get-CauRun](./Get-CauRun.md) +[Get-CauRun](get-caurun.md) -[Stop-CauRun](./Stop-CauRun.md) +[Invoke-CauScan](invoke-causcan.md) +[Stop-CauRun](stop-caurun.md) diff --git a/docset/winserver2022-ps/clusterawareupdating/Invoke-CauScan.md b/docset/winserver2022-ps/clusterawareupdating/Invoke-CauScan.md index 13a4fda860..bf29331ebd 100644 --- a/docset/winserver2022-ps/clusterawareupdating/Invoke-CauScan.md +++ b/docset/winserver2022-ps/clusterawareupdating/Invoke-CauScan.md @@ -17,8 +17,9 @@ updates that are applied to each node in a specified cluster. ## SYNTAX ``` -Invoke-CauScan [[-ClusterName] ] [[-CauPluginName] ] [[-Credential] -] [-CauPluginArguments ] [-RunPluginsSerially] [-StopOnPluginFailure] +Invoke-CauScan [[-ClusterName] ] [[-CauPluginName] ] + [[-Credential] ] [-CauPluginArguments ] [-RunPluginsSerially] + [-StopOnPluginFailure] [-OsRollingUpgrade] [-AttemptSoftReboot] [-RebootMode ] [] ``` @@ -43,10 +44,10 @@ Invoke-CauScan -ClusterName "CONTOSO-FC1" -CauPluginName "Microsoft.WindowsUpdat ``` This command gets a detailed list of the initial set of updates that would currently be applied to -each node in the cluster named CONTOSO-FC1. The list is based on the updates that would be applied -by the **Microsoft.WindowsUpdatePlugin** plug-in, which is the default plug-in. The preview list -includes only an initial set of updates, and doesn't include updates that might become applicable -only after the initial updates are installed. +each node in the cluster named **CONTOSO-FC1**. The list is based on the updates that would be +applied by the **Microsoft.WindowsUpdatePlugin** plug-in, which is the default plug-in. The preview +list includes only an initial set of updates, and doesn't include updates that might become +applicable only after the initial updates are installed. ### Example 2: Get a detailed list of the initial set of updates on the specified cluster using a query string @@ -67,32 +68,57 @@ Invoke-CauScan $parameters -Credential $Cred ``` This example gets a detailed list of the initial set of updates that would currently be applied to -each node in the cluster named CONTOSO-FC1. The list is based on the updates that would be applied +each node in the cluster named **CONTOSO-FC1**. The list is based on the updates that would be applied by the **Microsoft.WindowsUpdatePlugin** plug-in, using a specified query string, and the **Microsoft.HotfixPlugin**, after the necessary hotfixes and the hotfix configuration file have been downloaded to `\\CauHotfixSrv\shareName`. This example also shows how to pass the administrative -credentials for cluster CONTOSO-FC1 to the cmdlet. +credentials for cluster `CONTOSO-FC1` to the cmdlet. This example uses splatting to pass parameter values from the `$parameters` variable to the command. Learn more about [Splatting](/powershell/module/microsoft.powershell.core/about/about_splatting). ## PARAMETERS +### -AttemptSoftReboot + +Indicates that command assumes a Kernel Soft Reboot (KSR) for the failover cluster. + +KSR bypasses BIOS/firmware initialization. +You can only use KSR for updates that do not require a BIOS/firmware initialization. + +```yaml +Type: SwitchParameter +Parameter Sets: (All) +Aliases: + +Required: False +Position: Named +Default value: None +Accept pipeline input: False +Accept wildcard characters: False +``` + ### -CauPluginArguments -Specifies a set of name=value pairs for each updating plug-in to use. -For instance, to specify a **Domain** argument for one plug-in: +Specifies a set of name=value pairs, as arguments, for each updating plug-in to use. + +For instance, to specify a Domain argument for one plug-in: + - `@{Domain=Domain.local}` -You can specify multiple pairs in a set separated with semicolons. -For instance: -- `@{name1=value1;name2=value2;name3=value3}` These name=value pairs must be meaningful to the - **CauPluginName** parameter that you specify. If you specify arguments for more than one plug-in, - provide the sets of name=value pairs in the order that you pass values into the **CauPluginName** - parameter, separated by commas. For instance: + +You can specify multiple pairs in a set separated with semicolons. For instance: + +- `@{name1=value1;name2=value2;name3=value3}` + +These name=value pairs must be meaningful to the **CauPluginName** parameter that you specify. If +you specify arguments for more than one plug-in, provide the sets of name=value pairs in the order +that you pass values in **CauPluginName**, separated by commas. For instance: + - `@{name1=value1;name2=value2;name3=value3},@{name4=value4;name5=value5}` -For the default **Microsoft.WindowsUpdatePlugin** plug-in, no arguments are needed. -The following arguments are optional: +For the default **Microsoft.WindowsUpdatePlugin** plug-in, no arguments are needed. The following +arguments are optional: + - **'IncludeRecommendedUpdates'='\'**: Boolean value to indicate that recommended updates will be applied in addition to important updates on each node. If not specified, the default value is False. @@ -104,14 +130,15 @@ The following arguments are optional: For more information about query strings for the default **Microsoft.WindowsUpdatePlugin** plug-in and the criteria such as IsInstalled that can be included in the query strings, see -[IUpdateSearcher::Search method](https://go.microsoft.com/fwlink/p/?LinkId=223304). +[IUpdateSearcher::Search method](/windows/win32/api/wuapi/nf-wuapi-iupdatesearcher-search). + +For the **Microsoft.HotfixPlugin** plug-in, the following argument is required: -For the **Microsoft.HotfixPlugin** plug-in. -the following argument is required: - **HotfixRootFolderPath=\**: The UNC path to a hotfix root folder in an SMB share with a - structure that contains the updates to apply and that contains the hotfix configuration file + structure that contains the updates to apply and that contains the hotfix configuration file. + +The following arguments are optional for the **Microsoft.HotfixPlugin** plug-in: -The following arguments are optional for the **Microsoft.HotfixPlugin** plug-in: - **RequireSmbEncryption=\**: Boolean value to indicate that SMB Encryption will be enforced for accessing data from the SMB share. If not specified, the default value is False. To ensure the integrity of the data accessed from the SMB share, the plug-in requires that the share is enabled @@ -122,10 +149,9 @@ The following arguments are optional for the **Microsoft.HotfixPlugin** plug-in: - **HotfixInstallerTimeoutMinutes=\**: The length of time in minutes that the plug-in allows the hotfix installer process to return. If not specified, the default value is 30 minutes. - **HotfixConfigFileName=\**: Name for the hotfix configuration file. If not specified, the - default name DefaultHotfixConfig.xml is used. - -For more information about required and optional arguments for the **Microsoft.HotfixPlugin** -plug-in, see [How CAU Plug-ins Work](https://go.microsoft.com/fwlink/p/?LinkId=235333). + default name `DefaultHotfixConfig.xml` is used. For more information about required and optional + arguments for the **Microsoft.HotfixPlugin** plug-in, see + [How Cluster-Aware Updating plug-ins work](/windows-server/failover-clustering/cluster-aware-updating-plug-ins). ```yaml Type: Hashtable[] @@ -145,9 +171,11 @@ Specifies one or more plug-ins to use when performing scans. You can specify mul separated with commas. The default is the **Microsoft.WindowsUpdatePlugin** plug-in. This plug-in coordinates the Windows Update Agent software resident on each cluster node, the same software that is used when updates are downloaded from Windows Update or Microsoft Update, or from a Windows -Server Update Services (WSUS) server. For more information about how plug-ins work with +Server Update Services (WSUS) server. + +For more information about how plug-ins work with Cluster-Aware Updating (CAU), see -[Cluster-Aware Updating plug-ins](https://go.microsoft.com/fwlink/p/?LinkId=235333). +[Cluster-Aware Updating plug-ins](/windows-server/failover-clustering/cluster-aware-updating-plug-ins). ```yaml Type: String[] @@ -195,15 +223,56 @@ Accept pipeline input: False Accept wildcard characters: False ``` +### -OsRollingUpgrade + +Indicates that the CAU cluster role scans for upgrades to the operating system of the cluster nodes +without stopping the Hyper-V or the Scale-Out File Server workloads. + +```yaml +Type: SwitchParameter +Parameter Sets: (All) +Aliases: + +Required: False +Position: Named +Default value: None +Accept pipeline input: False +Accept wildcard characters: False +``` + +### -RebootMode + +Specifies the type of reboot to use for each node in the cluster during the update. The available +values are: + +- `ClusProp` +- `FullReboot` +- `SoftReboot` +- `PluginCustomReboot` +- `OrchestratorDefault` + +```yaml +Type: RebootType +Parameter Sets: DefaultParamSet +Aliases: +Accepted values: ClusProp, FullReboot, SoftReboot, PluginCustomReboot, OrchestratorDefault + +Required: False +Position: Named +Default value: None +Accept pipeline input: False +Accept wildcard characters: False +``` + ### -RunPluginsSerially Indicates that CAU scans each cluster node for applicable updates and stages the updates for each plug-in in the plug-in order passed into the **CauPluginName** parameter then multiple plug-ins are used during a scan for updates -By default, CAU scans and stages the applicable updates for all plug-ins in parallel. -This parameter is valid only when multiple plug-ins are specified in the **CauPluginName** parameter. -If a single plug-in is specified, a warning appears. +By default, CAU scans and stages the applicable updates for all plug-ins in parallel. This +parameter is valid only when multiple plug-ins are specified in the **CauPluginName** parameter. If +a single plug-in is specified, a warning appears. ```yaml Type: SwitchParameter @@ -243,7 +312,7 @@ Accept wildcard characters: False This cmdlet supports the common parameters: -Debug, -ErrorAction, -ErrorVariable, -InformationAction, -InformationVariable, -OutVariable, -OutBuffer, -PipelineVariable, -Verbose, -WarningAction, and -WarningVariable. For more information, see -[about_CommonParameters](https://go.microsoft.com/fwlink/?LinkID=113216). +[about_CommonParameters](/powershell/module/microsoft.powershell.core/about/about_commonparameters). ## INPUTS @@ -251,11 +320,20 @@ This cmdlet supports the common parameters: -Debug, -ErrorAction, -ErrorVariable ## OUTPUTS -### Microsoft.ClusterAwareUpdating.CauUpdateInfo +### Microsoft.ClusterAwareUpdating.UpdateInfo + +### Microsoft.ClusterAwareUpdating.ActivityIdMap + +### Microsoft.ClusterAwareUpdating.UpgradeSetupInfo ## NOTES ## RELATED LINKS -[Invoke-CauRun](./Invoke-CauRun.md) +[Add-CauClusterRole](add-cauclusterrole.md) + +[Get-CauRun](get-caurun.md) + +[Invoke-CauRun](invoke-caurun.md) +[Stop-CauRun](stop-caurun.md) diff --git a/docset/winserver2022-ps/clusterawareupdating/Register-CauPlugin.md b/docset/winserver2022-ps/clusterawareupdating/Register-CauPlugin.md index 18b955519b..a760e339b6 100644 --- a/docset/winserver2022-ps/clusterawareupdating/Register-CauPlugin.md +++ b/docset/winserver2022-ps/clusterawareupdating/Register-CauPlugin.md @@ -29,7 +29,7 @@ because CAU uses the **Microsoft.WindowsUpdatePlugin** plug-in by default. This with the Windows Update Agent software resident on each node, the same software that is used when updates are downloaded from Windows Update or Microsoft Update, or from a Windows Server Update Services (WSUS) server. For more information about how plug-ins work in CAU, see -[How CAU Plug-ins Work](https://go.microsoft.com/fwlink/p/?LinkId=235333). +[How CAU Plug-ins Work](/windows-server/failover-clustering/cluster-aware-updating-plug-ins). ## EXAMPLES @@ -39,28 +39,12 @@ Services (WSUS) server. For more information about how plug-ins work in CAU, see Register-CauPlugin -Path "C:\PluginDevelopment\Plugin01.dll" -Force ``` -The command registers a plug-in called Plugin01.dll located in the C:\PluginDevelopment folder. -Because the command specifies the **Force** parameter, the cmdlet runs without displaying confirmation -prompts. +The command registers a plug-in called **Plugin01.dll** located in the `C:\PluginDevelopment` folder. +Because the command specifies the **Force** parameter, the cmdlet runs without displaying +confirmation prompts. ## PARAMETERS -### -Confirm - -Prompts you for confirmation before running the cmdlet. - -```yaml -Type: SwitchParameter -Parameter Sets: (All) -Aliases: cf - -Required: False -Position: Named -Default value: False -Accept pipeline input: False -Accept wildcard characters: False -``` - ### -Path Specifies the path to the binary that implements the plug-in. Classes that implement the plug-in @@ -79,6 +63,22 @@ Accept pipeline input: False Accept wildcard characters: False ``` +### -Confirm + +Prompts you for confirmation before running the cmdlet. + +```yaml +Type: SwitchParameter +Parameter Sets: (All) +Aliases: cf + +Required: False +Position: Named +Default value: False +Accept pipeline input: False +Accept wildcard characters: False +``` + ### -WhatIf Shows what would happen if the cmdlet runs. @@ -101,7 +101,7 @@ Accept wildcard characters: False This cmdlet supports the common parameters: -Debug, -ErrorAction, -ErrorVariable, -InformationAction, -InformationVariable, -OutVariable, -OutBuffer, -PipelineVariable, -Verbose, -WarningAction, and -WarningVariable. For more information, see -[about_CommonParameters](https://go.microsoft.com/fwlink/?LinkID=113216). +[about_CommonParameters](/powershell/module/microsoft.powershell.core/about/about_commonparameters). ## INPUTS @@ -115,7 +115,6 @@ This cmdlet supports the common parameters: -Debug, -ErrorAction, -ErrorVariable ## RELATED LINKS -[Get-CauPlugin](./Get-CauPlugin.md) - -[Unregister-CauPlugin](./Unregister-CauPlugin.md) +[Get-CauPlugin](get-cauplugin.md) +[Unregister-CauPlugin](unregister-cauplugin.md) diff --git a/docset/winserver2022-ps/clusterawareupdating/Save-CauDebugTrace.md b/docset/winserver2022-ps/clusterawareupdating/Save-CauDebugTrace.md index 9b6af814d9..8138d08c2a 100644 --- a/docset/winserver2022-ps/clusterawareupdating/Save-CauDebugTrace.md +++ b/docset/winserver2022-ps/clusterawareupdating/Save-CauDebugTrace.md @@ -17,7 +17,7 @@ Saves CAU debug tracing information to a local zip file. ``` Save-CauDebugTrace [[-ClusterName] ] [[-FilePath] ] [-Credential ] - [-RunId ] [-Force] [] + [-RunId ] [-Force] [-FeatureUpdateLogs ] [] ``` ## DESCRIPTION @@ -38,8 +38,8 @@ Compatibility Mode (HTTP-In)** firewall exception is enabled on each node. Save-CauDebugTrace -ClusterName "CONTOSO-FC1" -FilePath "C:\temp\testrun.zip" ``` -This command saves the debug tracing information for the cluster named CONTOSO-FC1, to a trace file -called `testrun.zip` in the `C:\temp` folder. +This command saves the debug tracing information for the cluster named **CONTOSO-FC1**, to a trace +file called `testrun.zip` in the `C:\temp` folder. ## PARAMETERS @@ -68,6 +68,22 @@ Specifies the administrative credentials for the target cluster. ```yaml Type: PSCredential Parameter Sets: (All) +Aliases: + +Required: False +Position: Named +Default value: None +Accept pipeline input: False +Accept wildcard characters: False +``` + +### -FeatureUpdateLogs + +Specifies feature update logs. + +```yaml +Type: FeatureUpdateLogs +Parameter Sets: (All) Aliases: Required: False @@ -131,7 +147,7 @@ Accept wildcard characters: False This cmdlet supports the common parameters: -Debug, -ErrorAction, -ErrorVariable, -InformationAction, -InformationVariable, -OutVariable, -OutBuffer, -PipelineVariable, -Verbose, -WarningAction, and -WarningVariable. For more information, see -[about_CommonParameters](https://go.microsoft.com/fwlink/?LinkID=113216). +[about_CommonParameters](/powershell/module/microsoft.powershell.core/about/about_commonparameters). ## INPUTS @@ -139,11 +155,12 @@ This cmdlet supports the common parameters: -Debug, -ErrorAction, -ErrorVariable ## OUTPUTS -### None +### Microsoft.ClusterAwareUpdating.ActivityIdMap + +### System.IO.FileInfo ## NOTES ## RELATED LINKS -[Invoke-CauRun](./Invoke-CauRun.md) - +[Invoke-CauRun](invoke-caurun.md) diff --git a/docset/winserver2022-ps/clusterawareupdating/Set-CauClusterRole.md b/docset/winserver2022-ps/clusterawareupdating/Set-CauClusterRole.md index 9a90b2dade..0e9a56042f 100644 --- a/docset/winserver2022-ps/clusterawareupdating/Set-CauClusterRole.md +++ b/docset/winserver2022-ps/clusterawareupdating/Set-CauClusterRole.md @@ -25,8 +25,10 @@ Set-CauClusterRole [-UseDefault] [-StartDate ] [-DaysOfWeek [-RequireAllNodesOnline] [-WarnAfter ] [-StopAfter ] [-RebootTimeoutMinutes ] [-SeparateReboots] [-RunPluginsSerially] [-StopOnPluginFailure] [-EnableFirewallRules] [-FailbackMode ] [-SuspendClusterNodeTimeoutMinutes ] - [[-ClusterName] ] [[-Credential] ] [-Force] [-WhatIf] [-Confirm] - [] + [-ForcePauseNoDrain] [-ForcePauseAndDrain] [-ForcePauseDrainAndReboot] [-SkipUpdateChecks] + [-SiteAwareUpdatingOrder ] [-OsRollingUpgrade] [-AttemptSoftReboot] + [-RebootMode ] [[-ClusterName] ] [[-Credential] ] [-Force] + [-WhatIf] [-Confirm] [] ``` ### UpdateNow @@ -53,8 +55,25 @@ Set-CauClusterRole [-UseDefault] [-StartDate ] [-DaysOfWeek [-RequireAllNodesOnline] [-WarnAfter ] [-StopAfter ] [-RebootTimeoutMinutes ] [-SeparateReboots] [-RunPluginsSerially] [-StopOnPluginFailure] [-EnableFirewallRules] [-FailbackMode ] [-SuspendClusterNodeTimeoutMinutes ] - [[-ClusterName] ] [[-Credential] ] [-Force] [-WhatIf] [-Confirm] - [] + [-ForcePauseNoDrain] [-ForcePauseAndDrain] [-ForcePauseDrainAndReboot] [-SkipUpdateChecks] + [-SiteAwareUpdatingOrder ] [-OsRollingUpgrade] [-AttemptSoftReboot] + [-RebootMode ] [[-ClusterName] ] [[-Credential] ] [-Force] + [-WhatIf] [-Confirm] [] +``` + +### Once + +``` +Set-CauClusterRole [-UseDefault] [-RunOnce] [-CauPluginName ] + [-CauPluginArguments ] [-MaxFailedNodes ] [-MaxRetriesPerNode ] + [-NodeOrder ] [-PreUpdateScript ] [-PostUpdateScript ] + [-ConfigurationName ] [-RequireAllNodesOnline] [-WarnAfter ] + [-StopAfter ] [-RebootTimeoutMinutes ] [-SeparateReboots] [-RunPluginsSerially] + [-StopOnPluginFailure] [-EnableFirewallRules] [-FailbackMode ] + [-SuspendClusterNodeTimeoutMinutes ] [-ForcePauseNoDrain] [-ForcePauseAndDrain] + [-ForcePauseDrainAndReboot] [-SkipUpdateChecks] [-SiteAwareUpdatingOrder ] + [-OsRollingUpgrade] [-AttemptSoftReboot] [-RebootMode ] [[-ClusterName] ] + [[-Credential] ] [-Force] [-WhatIf] [-Confirm] [] ``` ## DESCRIPTION @@ -63,9 +82,9 @@ The `Set-CauClusterRole` cmdlet sets configuration properties for the Cluster-Aw clustered role on the specified cluster. This cmdlet can specify properties such as the updating schedule and updating run parameters. -To run this cmdlet with the **PostUpdateScript** or **PreUpdateScript** parameters, Windows PowerShell -remoting must be enabled on each node. To do this, use the `Enable-PSRemoting` cmdlet. In -addition, ensure that the **Windows Remote Management - Compatibility Mode (HTTP-In)** firewall +To run this cmdlet with the **PostUpdateScript** or **PreUpdateScript** parameters, Windows +PowerShell remoting must be enabled on each node. To do this, use the `Enable-PSRemoting` cmdlet. +In addition, ensure that the **Windows Remote Management - Compatibility Mode (HTTP-In)** firewall exception is enabled on each node. ## EXAMPLES @@ -83,17 +102,18 @@ $parameters = @{ Set-CauClusterRole $parameters ``` -This command configures settings for the CAU clustered role on the cluster named CONTOSO-FC1. The +This command configures settings for the CAU clustered role on the cluster named **CONTOSO-FC1**. The CAU clustered role is configured to perform updating runs on Tuesdays on the first and second weeks of each month. The CAU clustered role allows 10 minutes for the restarting of each node, if a restart is necessary. If the restart doesn't complete within this time, then the updating run on -that node is marked as failed. Because the command specifies the **Force** parameter, the cmdlet runs -without displaying confirmation prompts. +that node is marked as failed. Because the command specifies the **Force** parameter, the cmdlet +runs without displaying confirmation prompts. This example uses splatting to pass parameter values from the `$parameters` variable to the command. Learn more about [Splatting](/powershell/module/microsoft.powershell.core/about/about_splatting). ### Example 2: Configure settings for a CAU cluster role on the specified cluster on the second week of the month + ```powershell $parameters = @{ ClusterName = 'CONTOSO-FC1' @@ -119,14 +139,14 @@ DaysOfWeek Tuesday WeeksInterval 2 ``` -This command configures settings for the CAU clustered role on the cluster named CONTOSO-FC1. The +This command configures settings for the CAU clustered role on the cluster named **CONTOSO-FC1**. The CAU clustered role is configured to perform updating runs on Tuesdays on the second week of each month. The CAU clustered role allows 10 minutes for the restarting of each node, if a restart is necessary. If the restart doesn't complete within this time, then the updating run on that node is -marked as failed. The CAU clustered role runs a script after updating completes, just after the node -leaves Maintenance mode. The script is located at the root of drive G: in clustered storage and is -named verifyupdatesinstalled.ps1. Because the command specifies the **Force** parameter, the cmdlet -runs without displaying confirmation prompts. +marked as failed. The CAU clustered role runs a script after updating completes, just after the +node leaves Maintenance mode. The script is located at the root of drive G: in clustered storage +and is named `verifyupdatesinstalled.ps1`. Because the command specifies the **Force** parameter, +the cmdlet runs without displaying confirmation prompts. This example uses splatting to pass parameter values from the `$parameters` variable to the command. Learn more about [Splatting](/powershell/module/microsoft.powershell.core/about/about_splatting). @@ -138,7 +158,7 @@ Set-CauClusterRole -ClusterName "CONTOSO-FC1" -UpdateNow -Force ``` This command causes the CAU clustered role to initiate an updating run immediately on the cluster -named CONTOSO-FC1. Because the command specifies the **Force** parameter, the cmdlet runs without +named **CONTOSO-FC1**. Because the command specifies the **Force** parameter, the cmdlet runs without displaying confirmation prompts ### Example 4: Configure settings for a CAU cluster role on the specified cluster @@ -156,31 +176,56 @@ $parameters = @{ Set-CauClusterRole @parameters ``` -This example configures settings for the CAU clustered role on the cluster named CONTOSO-FC1. Time +This example configures settings for the CAU clustered role on the cluster named **CONTOSO-FC1**. Time spans are specified for logging a warning or canceling the updating run if it isn't completed. The earliest date that an updating run can be triggered is 1/1/2012. Because the command specifies the -**Force** parameter, the cmdlet runs without displaying confirmation prompts +**Force** parameter, the cmdlet runs without displaying confirmation prompts. This example uses splatting to pass parameter values from the `$parameters` variable to the command. Learn more about [Splatting](/powershell/module/microsoft.powershell.core/about/about_splatting). ## PARAMETERS +### -AttemptSoftReboot + +Indicates that the CAU clustered role attempts a Kernel Soft Reboot (KSR) for the failover cluster. + +KSR bypasses BIOS/firmware initialization. +You can only use KSR for updates that do not require a BIOS/firmware initialization. + +```yaml +Type: SwitchParameter +Parameter Sets: DefaultParamSet +Aliases: + +Required: False +Position: Named +Default value: None +Accept pipeline input: False +Accept wildcard characters: False +``` + ### -CauPluginArguments Specifies a set of name=value pairs, as arguments, for each updating plug-in to use. -For instance, to specify a Domain argument for one plug-in: + +For instance, to specify a Domain argument for one plug-in: + - `@{Domain=Domain.local}` -You can specify multiple pairs in a set separated with semicolons. -For instance: -- `@{name1=value1;name2=value2;name3=value3}` These name=value pairs must be meaningful to the - **CauPluginName** parameter that you specify. If you specify arguments for more than one plug-in, - provide the sets of name=value pairs in the order that you pass values in **CauPluginName**, - separated by commas. For instance: + +You can specify multiple pairs in a set separated with semicolons. For instance: + +- `@{name1=value1;name2=value2;name3=value3}` + +These name=value pairs must be meaningful to the **CauPluginName** parameter that you specify. If +you specify arguments for more than one plug-in, provide the sets of name=value pairs in the order +that you pass values in **CauPluginName**, separated by commas. For instance: + - `@{name1=value1;name2=value2;name3=value3},@{name4=value4;name5=value5}` -For the default **Microsoft.WindowsUpdatePlugin** plug-in, no arguments are needed. -The following arguments are optional: +For the default **Microsoft.WindowsUpdatePlugin** plug-in, no arguments are needed. The following +arguments are optional: + - **'IncludeRecommendedUpdates'='\'**: Boolean value to indicate that recommended updates will be applied in addition to important updates on each node. If not specified, the default value is False. @@ -188,16 +233,19 @@ The following arguments are optional: Agent to filter the updates that will be applied to each node. For a name, use **QueryString** and for a value, enclose the full query in quotation marks. If not specified, then the **Microsoft.WindowsUpdatePlugin** plug-in by default uses the following argument: -- `QueryString="IsInstalled=0 and Type='Software' and IsHidden=0 and IsAssigned=1"` For more - information about query strings for the default **Microsoft.WindowsUpdatePlugin** plug-in and the - criteria such as IsInstalled that can be included in the query strings, see - [IUpdateSearcher::Search method](https://go.microsoft.com/fwlink/p/?LinkId=223304). +- `QueryString="IsInstalled=0 and Type='Software' and IsHidden=0 and IsAssigned=1"` + +For more information about query strings for the default **Microsoft.WindowsUpdatePlugin** plug-in +and the criteria such as IsInstalled that can be included in the query strings, see +[IUpdateSearcher::Search method](/windows/win32/api/wuapi/nf-wuapi-iupdatesearcher-search). + +For the **Microsoft.HotfixPlugin** plug-in, the following argument is required: -For the **Microsoft.HotfixPlugin** plug-in, the following argument is required: - **HotfixRootFolderPath=\**: The UNC path to a hotfix root folder in an SMB share with a - structure that contains the updates to apply and that contains the hotfix configuration file + structure that contains the updates to apply and that contains the hotfix configuration file. + +The following arguments are optional for the **Microsoft.HotfixPlugin** plug-in: -The following arguments are optional for the **Microsoft.HotfixPlugin** plug-in: - **RequireSmbEncryption=\**: Boolean value to indicate that SMB Encryption will be enforced for accessing data from the SMB share. If not specified, the default value is False. To ensure the integrity of the data accessed from the SMB share, the plug-in requires that the share is enabled @@ -208,9 +256,9 @@ The following arguments are optional for the **Microsoft.HotfixPlugin** plug-in: - **HotfixInstallerTimeoutMinutes=\**: The length of time in minutes that the plug-in allows the hotfix installer process to return. If not specified, the default value is 30 minutes. - **HotfixConfigFileName=\**: Name for the hotfix configuration file. If not specified, the - default name DefaultHotfixConfig.xml is used. For more information about required and optional + default name `DefaultHotfixConfig.xml` is used. For more information about required and optional arguments for the **Microsoft.HotfixPlugin** plug-in, see - [How CAU Plug-ins Work](https://go.microsoft.com/fwlink/p/?LinkId=235333). + [How Cluster-Aware Updating plug-ins work](/windows-server/failover-clustering/cluster-aware-updating-plug-ins). ```yaml Type: Hashtable[] @@ -227,11 +275,11 @@ Accept wildcard characters: False ### -CauPluginName Specifies one or more plug-ins to use when performing scans or updates. You can specify multiple -values separated with commas. The default is the Microsoft.WindowsUpdatePlugin plug-in. This plug-in +values separated with commas. The default is the **Microsoft.WindowsUpdatePlugin** plug-in. This plug-in coordinates the Windows Update Agent software resident on each cluster node, the same software that is used when updates are downloaded from Windows Update or Microsoft Update, or from a Windows Server Update Services (WSUS) server. For more information about how plug-ins work with CAU, see -[How CAU Plug-ins Work](https://go.microsoft.com/fwlink/p/?LinkId=235333). +[How CAU Plug-ins Work](/windows-server/failover-clustering/cluster-aware-updating-plug-ins). ```yaml Type: String[] @@ -267,8 +315,8 @@ Accept wildcard characters: False ### -ConfigurationName Specifies the Windows PowerShell session configuration that defines the session in which scripts, -specified by the **PreUpdateScript** and **PostUpdateScript** parameters, and cmdlets are run, and can -limit the cmdlets that are available to be run. If either a pre-update or post-update script is +specified by the **PreUpdateScript** and **PostUpdateScript** parameters, and cmdlets are run, and +can limit the cmdlets that are available to be run. If either a pre-update or post-update script is specified but a configuration name isn't specified, then the default session configuration that is built into Windows PowerShell is used. @@ -284,22 +332,6 @@ Accept pipeline input: False Accept wildcard characters: False ``` -### -Confirm - -Prompts you for confirmation before running the cmdlet. - -```yaml -Type: SwitchParameter -Parameter Sets: (All) -Aliases: cf - -Required: False -Position: Named -Default value: False -Accept pipeline input: False -Accept wildcard characters: False -``` - ### -Credential Specifies the administrative credentials for the target cluster. @@ -319,15 +351,15 @@ Accept wildcard characters: False ### -DaysOfWeek Specifies the days of the week on which the task will be triggered. -Multiple values can be specified either separated with commas or as a hexadecimal sum. +Multiple values can be specified either separated with commas or as a hexadecimal sum. -- **Sunday:** (0x01) -- **Monday:** (0x02) -- **Tuesday:** (0x04) -- **Wednesday:** (0x08) -- **Thursday:** (0x10) -- **Friday:** (0x20) -- **Saturday:** (0x40) +- **Sunday:** (0x01) +- **Monday:** (0x02) +- **Tuesday:** (0x04) +- **Wednesday:** (0x08) +- **Thursday:** (0x10) +- **Friday:** (0x20) +- **Saturday:** (0x40) **Examples:** - **-DaysOfWeek:** Monday, Wednesday, Friday @@ -353,14 +385,14 @@ Indicates that this cmdlet enables the **Remote Shutdown** Windows Firewall rule cluster node, if it isn't already enabled, each time the CAU clustered role performs an Updating Run. Enabling this rule group permits inbound communication to each cluster node during each Updating Run that allows CAU to shut down and restart the node remotely. If Windows Firewall is in -use on the cluster nodes and the rule group isn't enabled, the updating run will fail. The **Remote -Shutdown** Windows Firewall rule group isn't enabled when it will conflict with Group Policy -settings that are configured for Windows Firewall. +use on the cluster nodes and the rule group is not enabled, the updating run will fail. The +**Remote Shutdown** Windows Firewall rule group is not enabled when it will conflict with Group +Policy settings that are configured for Windows Firewall. ```yaml Type: SwitchParameter -Parameter Sets: MonthlyDayOfWeek, Weekly -Aliases: +Parameter Sets: MonthlyDayOfWeek, Weekly, Once +Aliases: Required: False Position: Named @@ -382,8 +414,8 @@ another node. The acceptable values for this parameter are: ```yaml Type: FailbackType -Parameter Sets: MonthlyDayOfWeek, Weekly -Aliases: +Parameter Sets: MonthlyDayOfWeek, Weekly, Once +Aliases: Accepted values: NoFailback, Immediate, Policy Required: False @@ -409,11 +441,65 @@ Accept pipeline input: False Accept wildcard characters: False ``` +### -ForcePauseAndDrain + +Indicates that the CAU cluster role forces cluster nodes to pause and drain roles. + +A forced drain moves the roles off of the draining node even if the group cannot move. +A group might not be able to move because no other node can host the group or the group is locked. + +```yaml +Type: SwitchParameter +Parameter Sets: MonthlyDayOfWeek, Weekly, Once +Aliases: + +Required: False +Position: Named +Default value: None +Accept pipeline input: False +Accept wildcard characters: False +``` + +### -ForcePauseDrainAndReboot + +Indicates that the CAU cluster role forces cluster nodes to pause, drain roles, and restart. + +A forced drain moves the roles off of the draining node even if the group cannot move. +A group might not be able to move because no other node can host the group or the group is locked. + +```yaml +Type: SwitchParameter +Parameter Sets: MonthlyDayOfWeek, Weekly, Once +Aliases: + +Required: False +Position: Named +Default value: None +Accept pipeline input: False +Accept wildcard characters: False +``` + +### -ForcePauseNoDrain + +Indicates that the CAU cluster role forces cluster nodes to pause. +The nodes are not drained. + +```yaml +Type: SwitchParameter +Parameter Sets: MonthlyDayOfWeek, Weekly, Once +Aliases: + +Required: False +Position: Named +Default value: None +Accept pipeline input: False +Accept wildcard characters: False +``` + ### -IntervalWeeks -Specifies the interval between weeks when the task will be triggered. -An interval of 1 produces a weekly schedule. -An interval of 2 produces an every-other week schedule. +Specifies the interval between weeks when the task will be triggered. An interval of 1 produces a +weekly schedule. An interval of 2 produces an every-other week schedule. ```yaml Type: Int32 @@ -436,8 +522,8 @@ The default for most clusters is approximately one-third of the number of nodes. ```yaml Type: Int32 -Parameter Sets: MonthlyDayOfWeek, Weekly -Aliases: +Parameter Sets: MonthlyDayOfWeek, Weekly, Once +Aliases: Required: False Position: Named @@ -453,8 +539,8 @@ post-update scripts, is retried per node. The maximum is 64and the default is 3. ```yaml Type: Int32 -Parameter Sets: MonthlyDayOfWeek, Weekly -Aliases: +Parameter Sets: MonthlyDayOfWeek, Weekly, Once +Aliases: Required: False Position: Named @@ -469,8 +555,25 @@ Specifies an array of cluster node names in the order that they should be update ```yaml Type: String[] -Parameter Sets: MonthlyDayOfWeek, Weekly -Aliases: +Parameter Sets: MonthlyDayOfWeek, Weekly, Once +Aliases: + +Required: False +Position: Named +Default value: None +Accept pipeline input: False +Accept wildcard characters: False +``` + +### -OsRollingUpgrade + +Indicates that the CAU cluster role upgrades the operating system of the cluster nodes without +stopping the Hyper-V or the Scale-Out File Server workloads. + +```yaml +Type: SwitchParameter +Parameter Sets: MonthlyDayOfWeek, Weekly, Once +Aliases: Required: False Position: Named @@ -482,15 +585,15 @@ Accept wildcard characters: False ### -PostUpdateScript Specifies the path and file name for a Windows PowerShell script to run after updating completes, -just after the node leaves Maintenance mode. The file name extension must be .ps1 and the total +just after the node leaves Maintenance mode. The file name extension must be `.ps1` and the total length of the path plus the file name must be no longer than 260 characters. As a best practice, the script should be located on a disk in cluster storage, to ensure that it is always accessible to all the cluster nodes. ```yaml Type: String -Parameter Sets: MonthlyDayOfWeek, Weekly -Aliases: +Parameter Sets: MonthlyDayOfWeek, Weekly, Once +Aliases: Required: False Position: Named @@ -502,7 +605,7 @@ Accept wildcard characters: False ### -PreUpdateScript Specifies the path and file name for a Windows PowerShell script to run on each node before updating -begins, and before the node is put into Maintenance mode. The file name extension must be .ps1 and +begins, and before the node is put into Maintenance mode. The file name extension must be `.ps1` and the total length of the path plus the file name must be no longer than 260 characters. As a best practice, the script should be located on a disk in cluster storage, to ensure that it is always accessible to all the cluster nodes. @@ -519,15 +622,39 @@ Accept pipeline input: False Accept wildcard characters: False ``` +### -RebootMode + +Specifies the type of reboot to use for each node in the cluster during the update. The available +values are: + +- `ClusProp` +- `FullReboot` +- `SoftReboot` +- `PluginCustomReboot` +- `OrchestratorDefault` + +```yaml +Type: RebootType +Parameter Sets: MonthlyDayOfWeek, Weekly, Once +Aliases: +Accepted values: ClusProp, FullReboot, SoftReboot, PluginCustomReboot, OrchestratorDefault + +Required: False +Position: Named +Default value: None +Accept pipeline input: False +Accept wildcard characters: False +``` + ### -RebootTimeoutMinutes -Specifies the time in minutes that CAU will allow for the restarting of a node. If the restart doesn't -complete within this time, then the updating run on that node is marked as failed. +Specifies the time in minutes that CAU will allow for the restarting of a node. If the restart +doesn't complete within this time, then the updating run on that node is marked as failed. ```yaml Type: Int32 -Parameter Sets: MonthlyDayOfWeek, Weekly -Aliases: +Parameter Sets: MonthlyDayOfWeek, Weekly, Once +Aliases: Required: False Position: Named @@ -542,8 +669,25 @@ Indicates that all cluster nodes must be online and reachable before updating be ```yaml Type: SwitchParameter -Parameter Sets: MonthlyDayOfWeek, Weekly -Aliases: +Parameter Sets: MonthlyDayOfWeek, Weekly, Once +Aliases: + +Required: False +Position: Named +Default value: None +Accept pipeline input: False +Accept wildcard characters: False +``` + +### -RunOnce + +Specifies that the CAU run should only be performed once, rather than on a recurring schedule. This +can be useful if you only need to perform a one-time update of your cluster nodes. + +```yaml +Type: SwitchParameter +Parameter Sets: Once +Aliases: Required: False Position: Named @@ -555,20 +699,20 @@ Accept wildcard characters: False ### -RunPluginsSerially Indicates that CAU scans each cluster node for applicable updates and stage the updates for each -plug-in in the plug-in order passed into the*CauPluginName* parameter, when multiple plug-ins are +plug-in in the plug-in order passed into the**CauPluginName** parameter, when multiple plug-ins are used during an updating run. By default, CAU scans and stages the applicable updates for all plug-ins in parallel. Regardless of the configuration of this parameter, CAU installs the applicable updates for each plug-in sequentially. -The parameter is valid only when multiple plug-ins are specified in the **CauPluginName** parameter. If a -single plug-in is specified, a warning appears. +The parameter is valid only when multiple plug-ins are specified in the **CauPluginName** parameter. +If a single plug-in is specified, a warning appears. ```yaml Type: SwitchParameter -Parameter Sets: MonthlyDayOfWeek, Weekly -Aliases: +Parameter Sets: MonthlyDayOfWeek, Weekly, Once +Aliases: Required: False Position: Named @@ -589,8 +733,42 @@ If a single plug-in is specified, a warning appears. ```yaml Type: SwitchParameter -Parameter Sets: MonthlyDayOfWeek, Weekly -Aliases: +Parameter Sets: MonthlyDayOfWeek, Weekly, Once +Aliases: + +Required: False +Position: Named +Default value: None +Accept pipeline input: False +Accept wildcard characters: False +``` + +### -SiteAwareUpdatingOrder + +Specifies the order in which the CAU cluster role updates cluster nodes. + +By default, CAU selects the order of nodes to update based on the level of activity. + +```yaml +Type: String[] +Parameter Sets: MonthlyDayOfWeek, Weekly, Once +Aliases: + +Required: False +Position: Named +Default value: None +Accept pipeline input: False +Accept wildcard characters: False +``` + +### -SkipUpdateChecks + +Indicates that the CAU cluster role skips update checks. + +```yaml +Type: SwitchParameter +Parameter Sets: MonthlyDayOfWeek, Weekly, Once +Aliases: Required: False Position: Named @@ -627,8 +805,8 @@ performing updates must be complete within this time limit. ```yaml Type: TimeSpan -Parameter Sets: MonthlyDayOfWeek, Weekly -Aliases: +Parameter Sets: MonthlyDayOfWeek, Weekly, Once +Aliases: Required: False Position: Named @@ -648,8 +826,8 @@ If a single plug-in is specified, a warning appears. ```yaml Type: SwitchParameter -Parameter Sets: MonthlyDayOfWeek, Weekly -Aliases: +Parameter Sets: MonthlyDayOfWeek, Weekly, Once +Aliases: Required: False Position: Named @@ -660,8 +838,8 @@ Accept wildcard characters: False ### -SuspendClusterNodeTimeoutMinutes -Specifies the maximum amount of time CAU should wait for the `Suspend-ClusterNode` cmdlet to succeed if -the underlying clustered space is in degraded condition. +Specifies the maximum amount of time CAU should wait for the `Suspend-ClusterNode` cmdlet to +succeed if the underlying clustered space is in degraded condition. If `Suspend-ClusterNode` fails with ERROR_CLUSTER_SPACE_DEGRADED error, CAU will keep retrying for **SuspendClusterNodeTimeoutMinutes** or suspend the call if the command succeeds. @@ -673,8 +851,8 @@ for this value for every node in the cluster in the worst case. ```yaml Type: Int32 -Parameter Sets: MonthlyDayOfWeek, Weekly -Aliases: +Parameter Sets: MonthlyDayOfWeek, Weekly, Once +Aliases: Required: False Position: Named @@ -706,8 +884,8 @@ Indicates that default values are used for all parameters that don't have specif ```yaml Type: SwitchParameter -Parameter Sets: MonthlyDayOfWeek, UseDefault, Weekly -Aliases: +Parameter Sets: MonthlyDayOfWeek, UseDefault, Weekly, Once +Aliases: Required: False Position: Named @@ -724,8 +902,8 @@ of the time taken by the updating run. ```yaml Type: TimeSpan -Parameter Sets: MonthlyDayOfWeek, Weekly -Aliases: +Parameter Sets: MonthlyDayOfWeek, Weekly, Once +Aliases: Required: False Position: Named @@ -751,6 +929,22 @@ Accept pipeline input: False Accept wildcard characters: False ``` +### -Confirm + +Prompts you for confirmation before running the cmdlet. + +```yaml +Type: SwitchParameter +Parameter Sets: (All) +Aliases: cf + +Required: False +Position: Named +Default value: False +Accept pipeline input: False +Accept wildcard characters: False +``` + ### -WhatIf Shows what would happen if the cmdlet runs. @@ -773,7 +967,7 @@ Accept wildcard characters: False This cmdlet supports the common parameters: -Debug, -ErrorAction, -ErrorVariable, -InformationAction, -InformationVariable, -OutVariable, -OutBuffer, -PipelineVariable, -Verbose, -WarningAction, and -WarningVariable. For more information, see -[about_CommonParameters](https://go.microsoft.com/fwlink/?LinkID=113216). +[about_CommonParameters](/powershell/module/microsoft.powershell.core/about/about_commonparameters). ## INPUTS @@ -781,19 +975,18 @@ This cmdlet supports the common parameters: -Debug, -ErrorAction, -ErrorVariable ## OUTPUTS -### None +### System.Object ## NOTES ## RELATED LINKS -[Add-CauClusterRole](./Add-CauClusterRole.md) - -[Disable-CauClusterRole](./Disable-CauClusterRole.md) +[Add-CauClusterRole](add-cauclusterrole.md) -[Enable-CauClusterRole](./Enable-CauClusterRole.md) +[Disable-CauClusterRole](disable-cauclusterrole.md) -[Get-CauClusterRole](./Get-CauClusterRole.md) +[Enable-CauClusterRole](enable-cauclusterrole.md) -[Remove-CauClusterRole](./Remove-CauClusterRole.md) +[Get-CauClusterRole](get-cauclusterrole.md) +[Remove-CauClusterRole](remove-cauclusterrole.md) diff --git a/docset/winserver2022-ps/defender/Add-MpPreference.md b/docset/winserver2022-ps/defender/Add-MpPreference.md index 96c95090d6..ee236d0673 100644 --- a/docset/winserver2022-ps/defender/Add-MpPreference.md +++ b/docset/winserver2022-ps/defender/Add-MpPreference.md @@ -16,14 +16,23 @@ Modifies settings for Windows Defender. ## SYNTAX ``` -Add-MpPreference [-ExclusionPath ] [-ExclusionExtension ] -[-ExclusionProcess ] [-ExclusionIpAddress ] -[-ThreatIDDefaultAction_Ids ] [-ThreatIDDefaultAction_Actions ] -[-AttackSurfaceReductionOnlyExclusions ] -[-ControlledFolderAccessAllowedApplications ] -[-ControlledFolderAccessProtectedFolders ] [-AttackSurfaceReductionRules_Ids ] -[-AttackSurfaceReductionRules_Actions ] [-Force] [-CimSession ] -[-ThrottleLimit ] [-AsJob] [] +Add-MpPreference + [-AsJob] + [-AttackSurfaceReductionOnlyExclusions ] + [-AttackSurfaceReductionRules_Actions ] + [-AttackSurfaceReductionRules_Ids ] + [-CimSession ] + [-ControlledFolderAccessAllowedApplications ] + [-ControlledFolderAccessProtectedFolders ] + [-ExclusionExtension ] + [-ExclusionIpAddress ] + [-ExclusionPath ] + [-ExclusionProcess ] + [-Force] + [-ThreatIDDefaultAction_Actions ] + [-ThreatIDDefaultAction_Ids ] + [-ThrottleLimit ] + [] ``` ## DESCRIPTION @@ -69,7 +78,7 @@ For more information about Windows PowerShell background jobs, see ```yaml Type: SwitchParameter Parameter Sets: (All) -Aliases: +Aliases: Required: False Position: Named @@ -212,7 +221,7 @@ Specifies an array of IP addresses to exclude from scheduled and real-time scann ```yaml Type: String[] Parameter Sets: (All) -Aliases: +Aliases: Required: False Position: Named @@ -229,7 +238,7 @@ You can specify a folder to exclude all the files under the folder. ```yaml Type: String[] Parameter Sets: (All) -Aliases: +Aliases: Required: False Position: Named @@ -248,7 +257,7 @@ themselves. To exclude a process, specify it by using the **ExclusionPath** para ```yaml Type: String[] Parameter Sets: (All) -Aliases: +Aliases: Required: False Position: Named @@ -264,7 +273,7 @@ Forces the command to run without asking for user confirmation. ```yaml Type: SwitchParameter Parameter Sets: (All) -Aliases: +Aliases: Required: False Position: Named @@ -327,7 +336,7 @@ computer. ```yaml Type: Int32 Parameter Sets: (All) -Aliases: +Aliases: Required: False Position: Named diff --git a/docset/winserver2022-ps/defender/Get-MpComputerStatus.md b/docset/winserver2022-ps/defender/Get-MpComputerStatus.md index 7df4a2e7d7..f552e60318 100644 --- a/docset/winserver2022-ps/defender/Get-MpComputerStatus.md +++ b/docset/winserver2022-ps/defender/Get-MpComputerStatus.md @@ -16,8 +16,11 @@ Gets the status of antimalware software on the computer. ## SYNTAX ``` -Get-MpComputerStatus [-CimSession ] [-ThrottleLimit ] [-AsJob] -[] +Get-MpComputerStatus + [-AsJob] + [-CimSession ] + [-ThrottleLimit ] + [] ``` ## DESCRIPTION @@ -29,7 +32,7 @@ computer. ### Example 1: Get the computer status -``` +```powershell PS C:\> Get-MpComputerStatus AMEngineVersion : 1.1.24050.5 AMProductVersion : 4.18.24050.7 @@ -45,18 +48,18 @@ AntivirusSignatureAge : 1 AntivirusSignatureLastUpdated : 6/4/2024 8:06:27 AM AntivirusSignatureVersion : 1.413.102.0 BehaviorMonitorEnabled : True -ComputerID : +ComputerID : ComputerState : 0 DefenderSignaturesOutOfDate : False -DeviceControlDefaultEnforcement : +DeviceControlDefaultEnforcement : DeviceControlPoliciesLastUpdated : 12/31/1600 4:00:00 PM DeviceControlState : Disabled FullScanAge : 4294967295 -FullScanEndTime : +FullScanEndTime : FullScanOverdue : False FullScanRequired : False -FullScanSignatureVersion : -FullScanStartTime : +FullScanSignatureVersion : +FullScanStartTime : InitializationProgress : ServiceStartedSuccessfully IoavProtectionEnabled : True IsTamperProtected : False @@ -71,14 +74,14 @@ NISSignatureVersion : 1.413.102.0 OnAccessProtectionEnabled : True ProductStatus : 524288 QuickScanAge : 4294967295 -QuickScanEndTime : +QuickScanEndTime : QuickScanOverdue : False -QuickScanSignatureVersion : -QuickScanStartTime : +QuickScanSignatureVersion : +QuickScanStartTime : RealTimeProtectionEnabled : True RealTimeScanDirection : 0 RebootRequired : False -SmartAppControlExpiration : +SmartAppControlExpiration : SmartAppControlState : Off TamperProtectionSource : E5 transition TDTCapable : N/A @@ -95,7 +98,6 @@ TroubleShootingModeSource : ATP TroubleShootingQuotaResetTime : 6/5/2024 4:47:42 PM TroubleShootingStartTime : N/A PSComputerName : - ``` This command gets the status of antimalware protection software installed on the computer. @@ -118,7 +120,7 @@ For more information about Windows PowerShell background jobs, see ```yaml Type: SwitchParameter Parameter Sets: (All) -Aliases: +Aliases: Required: False Position: Named @@ -157,7 +159,7 @@ computer. ```yaml Type: Int32 Parameter Sets: (All) -Aliases: +Aliases: Required: False Position: Named diff --git a/docset/winserver2022-ps/defender/Get-MpPreference.md b/docset/winserver2022-ps/defender/Get-MpPreference.md index edc27371bf..d2e0728fbc 100644 --- a/docset/winserver2022-ps/defender/Get-MpPreference.md +++ b/docset/winserver2022-ps/defender/Get-MpPreference.md @@ -16,8 +16,11 @@ Gets preferences for the Windows Defender scans and updates. ## SYNTAX ``` -Get-MpPreference [-CimSession ] [-ThrottleLimit ] [-AsJob] -[] +Get-MpPreference + [-AsJob] + [-CimSession ] + [-ThrottleLimit ] + [] ``` ## DESCRIPTION @@ -30,7 +33,7 @@ information about the preferences that this cmdlet retrieves, see ### Example 1: View the scheduled scan day -``` +```powershell PS C:\> $Preferences = Get-MpPreference PS C:\> $Preferences.ScanScheduleDay ``` @@ -58,7 +61,7 @@ For more information about Windows PowerShell background jobs, see ```yaml Type: SwitchParameter Parameter Sets: (All) -Aliases: +Aliases: Required: False Position: Named @@ -97,7 +100,7 @@ computer. ```yaml Type: Int32 Parameter Sets: (All) -Aliases: +Aliases: Required: False Position: Named diff --git a/docset/winserver2022-ps/defender/Get-MpThreat.md b/docset/winserver2022-ps/defender/Get-MpThreat.md index 73688aa3a1..8aaf595196 100644 --- a/docset/winserver2022-ps/defender/Get-MpThreat.md +++ b/docset/winserver2022-ps/defender/Get-MpThreat.md @@ -24,8 +24,12 @@ Get-MpThreat [] ### ById ``` -Get-MpThreat [-ThreatID ] [-CimSession ] [-ThrottleLimit ] [-AsJob] -[] +Get-MpThreat + [-AsJob] + [-CimSession ] + [-ThreatID ] + [-ThrottleLimit ] + [] ``` ## DESCRIPTION @@ -37,7 +41,7 @@ computer. ### Example 1: Get the history of a detected threat -``` +```powershell PS C:\> Get-MpThreat -ThreatID 1994 ``` @@ -61,7 +65,7 @@ For more information about Windows PowerShell background jobs, see ```yaml Type: SwitchParameter Parameter Sets: ById -Aliases: +Aliases: Required: False Position: Named @@ -117,7 +121,7 @@ computer. ```yaml Type: Int32 Parameter Sets: ById -Aliases: +Aliases: Required: False Position: Named @@ -146,4 +150,3 @@ This cmdlet supports the common parameters: -Debug, -ErrorAction, -ErrorVariable [Get-MpThreatCatalog](./Get-MpThreatCatalog.md) [Get-MpThreatDetection](./Get-MpThreatDetection.md) - diff --git a/docset/winserver2022-ps/defender/Get-MpThreatCatalog.md b/docset/winserver2022-ps/defender/Get-MpThreatCatalog.md index b6999aafca..ab8a7b2ca8 100644 --- a/docset/winserver2022-ps/defender/Get-MpThreatCatalog.md +++ b/docset/winserver2022-ps/defender/Get-MpThreatCatalog.md @@ -24,7 +24,11 @@ Get-MpThreatCatalog [] ### ById ``` -Get-MpThreatCatalog [-ThreatID ] [-CimSession ] [-ThrottleLimit ] [-AsJob] +Get-MpThreatCatalog + [-AsJob] + [-CimSession ] + [-ThreatID ] + [-ThrottleLimit ] [] ``` @@ -37,7 +41,7 @@ The definitions catalog contains references to all known threats that Windows De ### Example 1: Get a known threat from the definitions catalog -``` +```powershell PS C:\> Get-MpThreatCatalog -ThreatID 1994 ``` @@ -61,7 +65,7 @@ For more information about Windows PowerShell background jobs, see ```yaml Type: SwitchParameter Parameter Sets: ById -Aliases: +Aliases: Required: False Position: Named @@ -117,7 +121,7 @@ computer. ```yaml Type: Int32 Parameter Sets: ById -Aliases: +Aliases: Required: False Position: Named diff --git a/docset/winserver2022-ps/defender/Get-MpThreatDetection.md b/docset/winserver2022-ps/defender/Get-MpThreatDetection.md index 3db6f72ffb..a7e21788c6 100644 --- a/docset/winserver2022-ps/defender/Get-MpThreatDetection.md +++ b/docset/winserver2022-ps/defender/Get-MpThreatDetection.md @@ -22,7 +22,11 @@ Get-MpThreatDetection [] ### ById ``` -Get-MpThreatDetection [-ThreatID ] [-CimSession ] [-ThrottleLimit ] [-AsJob] +Get-MpThreatDetection + [-AsJob] + [-CimSession ] + [-ThreatID ] + [-ThrottleLimit ] [] ``` @@ -33,7 +37,7 @@ If Windows Defender has detected the threat that you specify, this cmdlet return ## EXAMPLES ### Example 1: Get threats that Windows Defender detected -``` +```powershell PS C:\> Get-MpThreatDetection ``` @@ -41,7 +45,7 @@ This command returns the list of past malware detections for the local computer. **Error codes** -The following table lists the hexadecimal and decimal error codes for this cmdlet. Each hexadecimal error code has a 0x8050 prefix. Therefore, an ERROR_MP_BAD_SCANID error corresponds to error code 0x80508012. Additionally, an ERR_MP_REMOVE_FAILED error corresponds to error code 0x80508017. +The following table lists the hexadecimal and decimal error codes for this cmdlet. Each hexadecimal error code has a 0x8050 prefix. Therefore, an ERROR_MP_BAD_SCANID error corresponds to error code 0x80508012. Additionally, an ERR_MP_REMOVE_FAILED error corresponds to error code 0x80508017. For a list of error codes, along with possible reasons and resolutions, see [Windows Defender Antivirus client error codes](/windows/security/threat-protection/windows-defender-antivirus/troubleshoot-windows-defender-antivirus#windows-defender-antivirus-client-error-codes) in the topic [Review event logs and error codes to troubleshoot issues with Windows Defender Antivirus](/windows/security/threat-protection/windows-defender-antivirus/troubleshoot-windows-defender-antivirus#windows-defender-antivirus-client-error-codes). @@ -87,19 +91,19 @@ For a list of error codes, along with possible reasons and resolutions, see [Win ## PARAMETERS ### -AsJob -Runs the cmdlet as a background job. Use this parameter to run commands that take a long time to complete. +Runs the cmdlet as a background job. Use this parameter to run commands that take a long time to complete. -The cmdlet immediately returns an object that represents the job and then displays the command prompt. -You can continue to work in the session while the job completes. -To manage the job, use the `*-Job` cmdlets. -To get the job results, use the [Receive-Job](https://go.microsoft.com/fwlink/?LinkID=113372) cmdlet. +The cmdlet immediately returns an object that represents the job and then displays the command prompt. +You can continue to work in the session while the job completes. +To manage the job, use the `*-Job` cmdlets. +To get the job results, use the [Receive-Job](https://go.microsoft.com/fwlink/?LinkID=113372) cmdlet. For more information about Windows PowerShell background jobs, see [about_Jobs](https://go.microsoft.com/fwlink/?LinkID=113251). ```yaml Type: SwitchParameter Parameter Sets: ById -Aliases: +Aliases: Required: False Position: Named @@ -109,8 +113,8 @@ Accept wildcard characters: False ``` ### -CimSession -Runs the cmdlet in a remote session or on a remote computer. -Enter a computer name or a session object, such as the output of a [New-CimSession](https://go.microsoft.com/fwlink/p/?LinkId=227967) or [Get-CimSession](https://go.microsoft.com/fwlink/p/?LinkId=227966) cmdlet. +Runs the cmdlet in a remote session or on a remote computer. +Enter a computer name or a session object, such as the output of a [New-CimSession](https://go.microsoft.com/fwlink/p/?LinkId=227967) or [Get-CimSession](https://go.microsoft.com/fwlink/p/?LinkId=227966) cmdlet. The default is the current session on the local computer. ```yaml @@ -149,7 +153,7 @@ The throttle limit applies only to the current cmdlet, not to the session or to ```yaml Type: Int32 Parameter Sets: ById -Aliases: +Aliases: Required: False Position: Named diff --git a/docset/winserver2022-ps/defender/Remove-MpPreference.md b/docset/winserver2022-ps/defender/Remove-MpPreference.md index c10d0138f9..2d767983b2 100644 --- a/docset/winserver2022-ps/defender/Remove-MpPreference.md +++ b/docset/winserver2022-ps/defender/Remove-MpPreference.md @@ -16,36 +16,105 @@ Removes exclusions or default actions. ## SYNTAX ``` -Remove-MpPreference [-ExclusionPath ] [-ExclusionExtension ] [-ExclusionProcess ] - [-ExclusionIpAddress ] [-RealTimeScanDirection] [-QuarantinePurgeItemsAfterDelay] - [-RemediationScheduleDay] [-RemediationScheduleTime] [-ReportingAdditionalActionTimeOut] - [-ReportingCriticalFailureTimeOut] [-ReportingNonCriticalTimeOut] [-ScanAvgCPULoadFactor] - [-CheckForSignaturesBeforeRunningScan] [-ScanPurgeItemsAfterDelay] [-ScanOnlyIfIdleEnabled] [-ScanParameters] - [-ScanScheduleDay] [-ScanScheduleQuickScanTime] [-ScanScheduleTime] [-SignatureFirstAuGracePeriod] - [-SignatureAuGracePeriod] [-SignatureDefinitionUpdateFileSharesSources] - [-SignatureDisableUpdateOnStartupWithoutEngine] [-SignatureFallbackOrder] [-SharedSignaturesPath] - [-SignatureScheduleDay] [-SignatureScheduleTime] [-SignatureUpdateCatchupInterval] [-SignatureUpdateInterval] - [-SignatureBlobUpdateInterval] [-SignatureBlobFileSharesSources] [-MeteredConnectionUpdates] - [-AllowNetworkProtectionOnWinServer] [-DisableDatagramProcessing] [-DisableCpuThrottleOnIdleScans] - [-MAPSReporting] [-SubmitSamplesConsent] [-DisableAutoExclusions] [-DisablePrivacyMode] - [-RandomizeScheduleTaskTimes] [-SchedulerRandomizationTime] [-DisableBehaviorMonitoring] - [-DisableIntrusionPreventionSystem] [-DisableIOAVProtection] [-DisableRealtimeMonitoring] - [-DisableScriptScanning] [-DisableArchiveScanning] [-DisableCatchupFullScan] [-DisableCatchupQuickScan] - [-DisableEmailScanning] [-DisableRemovableDriveScanning] [-DisableRestorePoint] - [-DisableScanningMappedNetworkDrivesForFullScan] [-DisableScanningNetworkFiles] [-UILockdown] - [-ThreatIDDefaultAction_Ids ] [-ThreatIDDefaultAction_Actions ] - [-UnknownThreatDefaultAction] [-LowThreatDefaultAction] [-ModerateThreatDefaultAction] - [-HighThreatDefaultAction] [-SevereThreatDefaultAction] [-DisableBlockAtFirstSeen] [-PUAProtection] - [-CloudBlockLevel] [-CloudExtendedTimeout] [-EnableNetworkProtection] [-EnableControlledFolderAccess] - [-AttackSurfaceReductionOnlyExclusions ] [-ControlledFolderAccessAllowedApplications ] - [-ControlledFolderAccessProtectedFolders ] [-AttackSurfaceReductionRules_Ids ] - [-AttackSurfaceReductionRules_Actions ] [-EnableLowCpuPriority] - [-EnableFileHashComputation] [-EnableFullScanOnBatteryPower] [-ProxyPacUrl] [-ProxyServer] [-ProxyBypass] - [-ForceUseProxyOnly] [-DisableTlsParsing] [-DisableHttpParsing] [-DisableDnsParsing] - [-DisableDnsOverTcpParsing] [-DisableSshParsing] [-PlatformUpdatesChannel] [-EngineUpdatesChannel] - [-SignaturesUpdatesChannel] [-DisableGradualRelease] [-AllowNetworkProtectionDownLevel] - [-AllowDatagramProcessingOnWinServer] [-EnableDnsSinkhole] [-DisableInboundConnectionFiltering] - [-DisableRdpParsing] [-Force] [-CimSession ] [-ThrottleLimit ] [-AsJob] +Remove-MpPreference + [-AllowDatagramProcessingOnWinServer] + [-AllowNetworkProtectionDownLevel] + [-AllowNetworkProtectionOnWinServer] + [-AsJob] + [-AttackSurfaceReductionOnlyExclusions ] + [-AttackSurfaceReductionRules_Actions ] + [-AttackSurfaceReductionRules_Ids ] + [-CheckForSignaturesBeforeRunningScan] + [-CimSession ] + [-CloudBlockLevel] + [-CloudExtendedTimeout] + [-ControlledFolderAccessAllowedApplications ] + [-ControlledFolderAccessProtectedFolders ] + [-DisableArchiveScanning] + [-DisableAutoExclusions] + [-DisableBehaviorMonitoring] + [-DisableBlockAtFirstSeen] + [-DisableCatchupFullScan] + [-DisableCatchupQuickScan] + [-DisableCpuThrottleOnIdleScans] + [-DisableDatagramProcessing] + [-DisableDnsOverTcpParsing] + [-DisableDnsParsing] + [-DisableEmailScanning] + [-DisableGradualRelease] + [-DisableHttpParsing] + [-DisableIOAVProtection] + [-DisableInboundConnectionFiltering] + [-DisableIntrusionPreventionSystem] + [-DisablePrivacyMode] + [-DisableRdpParsing] + [-DisableRealtimeMonitoring] + [-DisableRemovableDriveScanning] + [-DisableRestorePoint] + [-DisableScanningMappedNetworkDrivesForFullScan] + [-DisableScanningNetworkFiles] + [-DisableScriptScanning] + [-DisableSshParsing] + [-DisableTlsParsing] + [-EnableControlledFolderAccess] + [-EnableDnsSinkhole] + [-EnableFileHashComputation] + [-EnableFullScanOnBatteryPower] + [-EnableLowCpuPriority] + [-EnableNetworkProtection] + [-EngineUpdatesChannel] + [-ExclusionExtension ] + [-ExclusionIpAddress ] + [-ExclusionPath ] + [-ExclusionProcess ] + [-ForceUseProxyOnly] + [-Force] + [-HighThreatDefaultAction] + [-LowThreatDefaultAction] + [-MAPSReporting] + [-MeteredConnectionUpdates] + [-ModerateThreatDefaultAction] + [-PUAProtection] + [-PlatformUpdatesChannel] + [-ProxyBypass] + [-ProxyPacUrl] + [-ProxyServer] + [-QuarantinePurgeItemsAfterDelay] + [-RandomizeScheduleTaskTimes] + [-RealTimeScanDirection] + [-RemediationScheduleDay] + [-RemediationScheduleTime] + [-ReportingAdditionalActionTimeOut] + [-ReportingCriticalFailureTimeOut] + [-ReportingNonCriticalTimeOut] + [-ScanAvgCPULoadFactor] + [-ScanOnlyIfIdleEnabled] + [-ScanParameters] + [-ScanPurgeItemsAfterDelay] + [-ScanScheduleDay] + [-ScanScheduleQuickScanTime] + [-ScanScheduleTime] + [-SchedulerRandomizationTime] + [-SevereThreatDefaultAction] + [-SharedSignaturesPath] + [-SignatureAuGracePeriod] + [-SignatureBlobFileSharesSources] + [-SignatureBlobUpdateInterval] + [-SignatureDefinitionUpdateFileSharesSources] + [-SignatureDisableUpdateOnStartupWithoutEngine] + [-SignatureFallbackOrder] + [-SignatureFirstAuGracePeriod] + [-SignatureScheduleDay] + [-SignatureScheduleTime] + [-SignatureUpdateCatchupInterval] + [-SignatureUpdateInterval] + [-SignaturesUpdatesChannel] + [-SubmitSamplesConsent] + [-ThreatIDDefaultAction_Actions ] + [-ThreatIDDefaultAction_Ids ] + [-ThrottleLimit ] + [-UILockdown] + [-UnknownThreatDefaultAction] [] ``` @@ -56,14 +125,14 @@ If you attempt to remove an exclusion that is not in the list, this cmdlet repor ## EXAMPLES ### Example 1: Remove a folder from the exclusion list -``` +```powershell Remove-MpPreference -ExclusionPath "C:\Temp" ``` This command removes the folder C:\Temp from the exclusion list. ### Example 2: Exclude a specific file -``` +```powershell Remove-MpPreference -AttackSurfaceReductionOnlyExclusions "C:\Windows\App.exe" ``` @@ -117,19 +186,19 @@ Accept wildcard characters: False ``` ### -AsJob -Runs the cmdlet as a background job. Use this parameter to run commands that take a long time to complete. +Runs the cmdlet as a background job. Use this parameter to run commands that take a long time to complete. -The cmdlet immediately returns an object that represents the job and then displays the command prompt. -You can continue to work in the session while the job completes. -To manage the job, use the `*-Job` cmdlets. -To get the job results, use the [Receive-Job](https://go.microsoft.com/fwlink/?LinkID=113372) cmdlet. +The cmdlet immediately returns an object that represents the job and then displays the command prompt. +You can continue to work in the session while the job completes. +To manage the job, use the `*-Job` cmdlets. +To get the job results, use the [Receive-Job](https://go.microsoft.com/fwlink/?LinkID=113372) cmdlet. For more information about Windows PowerShell background jobs, see [about_Jobs](https://go.microsoft.com/fwlink/?LinkID=113251). ```yaml Type: SwitchParameter Parameter Sets: (All) -Aliases: +Aliases: Required: False Position: Named @@ -138,7 +207,6 @@ Accept pipeline input: False Accept wildcard characters: False ``` - ### -AttackSurfaceReductionOnlyExclusions Specifies the files and paths to exclude from Attack Surface Reduction (ASR) rules. Specify the folders or files and resources that should be excluded from ASR rules. Enter a folder path or a fully qualified resource name. For example, ""C:\Windows"" will exclude all files in that directory. ""C:\Windows\App.exe"" will exclude only that specific file in that specific folder. @@ -205,7 +273,7 @@ Accept wildcard characters: False ### -CimSession Runs the cmdlet in a remote session or on a remote computer. -Enter a computer name or a session object, such as the output of a [New-CimSession](https://go.microsoft.com/fwlink/p/?LinkId=227967) or [Get-CimSession](https://go.microsoft.com/fwlink/p/?LinkId=227966) cmdlet. +Enter a computer name or a session object, such as the output of a [New-CimSession](https://go.microsoft.com/fwlink/p/?LinkId=227967) or [Get-CimSession](https://go.microsoft.com/fwlink/p/?LinkId=227966) cmdlet. The default is the current session on the local computer. ```yaml @@ -448,15 +516,15 @@ Accept wildcard characters: False ``` ### -DisableGradualRelease -Indicates that the cmdlet removes whether to disable gradual rollout of monthly and daily Windows Defender updates. +Indicates that the cmdlet removes whether to disable gradual rollout of monthly and daily Windows Defender updates. If you enable this option, devices are offered all updates after the gradual release cycle finishes. -Consider this option for datacenter computers that only receive limited updates. +Consider this option for datacenter computers that only receive limited updates. This setting applies to both monthly and daily updates. -It overrides any previously configured channel selections for platform and engine updates. +It overrides any previously configured channel selections for platform and engine updates. If you disable or do not configure this policy, the device remains in Current Channel (Default) unless specified otherwise in specific channels for platform and engine updates. -The device stays up to date automatically during the gradual release cycle, which is suitable for most devices. +The device stays up to date automatically during the gradual release cycle, which is suitable for most devices. This policy is available starting with platform version 4.18.2106.5 and later. @@ -704,7 +772,7 @@ Accept wildcard characters: False ``` ### -EnableDnsSinkhole -Indicates that the cmdlet removes whether to examine DNS traffic to detect and sinkhole DNS exfiltration attempts and other DNS based malicious attacks. +Indicates that the cmdlet removes whether to examine DNS traffic to detect and sinkhole DNS exfiltration attempts and other DNS based malicious attacks. ```yaml Type: SwitchParameter @@ -825,7 +893,7 @@ Specifies an array of IP addresses to exclude from scheduled and real-time scann ```yaml Type: String[] Parameter Sets: (All) -Aliases: +Aliases: Required: False Position: Named @@ -841,7 +909,7 @@ This cmdlet removes the exclusions that you specify. ```yaml Type: String[] Parameter Sets: (All) -Aliases: +Aliases: Required: False Position: Named @@ -857,7 +925,7 @@ This cmdlet removes exclusions of files opened by the processes that you specify ```yaml Type: String[] Parameter Sets: (All) -Aliases: +Aliases: Required: False Position: Named @@ -872,7 +940,7 @@ Forces the command to run without asking for user confirmation. ```yaml Type: SwitchParameter Parameter Sets: (All) -Aliases: +Aliases: Required: False Position: Named @@ -1533,12 +1601,12 @@ Accept wildcard characters: False Specifies an array of the actions to take for the IDs specified by using the **ThreatIDDefaultAction_Ids** parameter. The acceptable values for this parameter are: -- 1: Clean -- 2: Quarantine -- 3: Remove -- 6: Allow -- 8: UserDefined -- 9: NoAction +- 1: Clean +- 2: Quarantine +- 3: Remove +- 6: Allow +- 8: UserDefined +- 9: NoAction - 10: Block >[!NOTE] @@ -1580,7 +1648,7 @@ The throttle limit applies only to the current cmdlet, not to the session or to ```yaml Type: Int32 Parameter Sets: (All) -Aliases: +Aliases: Required: False Position: Named diff --git a/docset/winserver2022-ps/defender/Remove-MpThreat.md b/docset/winserver2022-ps/defender/Remove-MpThreat.md index 368db9410d..0bd2725833 100644 --- a/docset/winserver2022-ps/defender/Remove-MpThreat.md +++ b/docset/winserver2022-ps/defender/Remove-MpThreat.md @@ -16,7 +16,11 @@ Removes active threats from a computer. ## SYNTAX ``` -Remove-MpThreat [-CimSession ] [-ThrottleLimit ] [-AsJob] [] +Remove-MpThreat + [-AsJob] + [-CimSession ] + [-ThrottleLimit ] + [] ``` ## DESCRIPTION @@ -25,7 +29,7 @@ The **Remove-MpThreat** cmdlet removes all active threats that Windows Defender ## EXAMPLES ### Example 1: Remove active threats from a computer -``` +```powershell PS C:\> Remove-MpThreat ``` @@ -34,19 +38,19 @@ This command removes all active threats from the local computer. ## PARAMETERS ### -AsJob -Runs the cmdlet as a background job. Use this parameter to run commands that take a long time to complete. +Runs the cmdlet as a background job. Use this parameter to run commands that take a long time to complete. -The cmdlet immediately returns an object that represents the job and then displays the command prompt. -You can continue to work in the session while the job completes. -To manage the job, use the `*-Job` cmdlets. -To get the job results, use the [Receive-Job](https://go.microsoft.com/fwlink/?LinkID=113372) cmdlet. +The cmdlet immediately returns an object that represents the job and then displays the command prompt. +You can continue to work in the session while the job completes. +To manage the job, use the `*-Job` cmdlets. +To get the job results, use the [Receive-Job](https://go.microsoft.com/fwlink/?LinkID=113372) cmdlet. For more information about Windows PowerShell background jobs, see [about_Jobs](https://go.microsoft.com/fwlink/?LinkID=113251). ```yaml Type: SwitchParameter Parameter Sets: (All) -Aliases: +Aliases: Required: False Position: Named @@ -56,8 +60,8 @@ Accept wildcard characters: False ``` ### -CimSession -Runs the cmdlet in a remote session or on a remote computer. -Enter a computer name or a session object, such as the output of a [New-CimSession](https://go.microsoft.com/fwlink/p/?LinkId=227967) or [Get-CimSession](https://go.microsoft.com/fwlink/p/?LinkId=227966) cmdlet. +Runs the cmdlet in a remote session or on a remote computer. +Enter a computer name or a session object, such as the output of a [New-CimSession](https://go.microsoft.com/fwlink/p/?LinkId=227967) or [Get-CimSession](https://go.microsoft.com/fwlink/p/?LinkId=227966) cmdlet. The default is the current session on the local computer. ```yaml @@ -80,7 +84,7 @@ The throttle limit applies only to the current cmdlet, not to the session or to ```yaml Type: Int32 Parameter Sets: (All) -Aliases: +Aliases: Required: False Position: Named diff --git a/docset/winserver2022-ps/defender/Set-MpPreference.md b/docset/winserver2022-ps/defender/Set-MpPreference.md index 6b4dccec70..9dae961c56 100644 --- a/docset/winserver2022-ps/defender/Set-MpPreference.md +++ b/docset/winserver2022-ps/defender/Set-MpPreference.md @@ -11,87 +11,157 @@ title: Set-MpPreference # Set-MpPreference ## SYNOPSIS + Configures preferences for Windows Defender scans and updates. -## SYNTAX +> [!NOTE] +> You need to run this cmdlet in an elevated PowerShell window (a PowerShell window you opened by +selecting **Run as administrator**). +## SYNTAX ```powershell -Set-MpPreference [-ExclusionPath ] [-ExclusionExtension ] [-ExclusionProcess ] - [-ExclusionIpAddress ] [-RealTimeScanDirection ] - [-IntelTDTEnabled ] - [-QuarantinePurgeItemsAfterDelay ] [-RemediationScheduleDay ] - [-RemediationScheduleTime ] [-ReportingAdditionalActionTimeOut ] - [-ReportingCriticalFailureTimeOut ] [-ReportingNonCriticalTimeOut ] - [-ScanAvgCPULoadFactor ] [-CheckForSignaturesBeforeRunningScan ] - [-ScanPurgeItemsAfterDelay ] [-ScanOnlyIfIdleEnabled ] [-ScanParameters ] - [-ScanScheduleDay ] [-ScanScheduleQuickScanTime ] [-ScanScheduleOffset ] - [-ScanScheduleTime ] - [-SignatureFirstAuGracePeriod ] [-SignatureAuGracePeriod ] - [-SignatureDefinitionUpdateFileSharesSources ] - [-SignatureDisableUpdateOnStartupWithoutEngine ] [-SignatureFallbackOrder ] - [-SharedSignaturesPath ] [-SignatureScheduleDay ] [-SignatureScheduleTime ] - [-SignatureUpdateCatchupInterval ] [-SignatureUpdateInterval ] - [-SignatureBlobUpdateInterval ] [-SignatureBlobFileSharesSources ] - [-MeteredConnectionUpdates ] [-AllowNetworkProtectionOnWinServer ] - [-DisableDatagramProcessing ] [-DisableCpuThrottleOnIdleScans ] - [-MAPSReporting ] [-SubmitSamplesConsent ] - [-DisableAutoExclusions ] [-DisablePrivacyMode ] [-RandomizeScheduleTaskTimes ] - [-SchedulerRandomizationTime ] [-DisableBehaviorMonitoring ] - [-DisableRealtimeMonitoring ] [-DisableScriptScanning ] [-DisableArchiveScanning ] [-DisableCacheMaintenance ] - [-DisableCatchupFullScan ] [-DisableCatchupQuickScan ] [-DisableEmailScanning ] - [-DisableRemovableDriveScanning ] [-DisableRestorePoint ] - [-DisableScanningMappedNetworkDrivesForFullScan ] [-DisableScanningNetworkFiles ] - [-DisableIOAVProtection ] [-AllowSwitchToAsyncInspection ] - [-UILockdown ] [-ThreatIDDefaultAction_Ids ] - [-ThreatIDDefaultAction_Actions ] [-UnknownThreatDefaultAction ] - [-LowThreatDefaultAction ] [-ModerateThreatDefaultAction ] - [-HighThreatDefaultAction ] [-SevereThreatDefaultAction ] [-Force] - [-DisableBlockAtFirstSeen ] [-PUAProtection ] - [-ThrottleLimit ] [-AsJob] [] [-DisableGradualRelease ] [-DefinitionUpdatesChannel ] [-EngineUpdatesChannel ] [-PlatformUpdatesChannel ][-CloudBlockLevel ][-ServiceHealthReportInterval ] - [-CloudBlockLevel ] [-CloudExtendedTimeout ] - [-EnableNetworkProtection ] [-EnableControlledFolderAccess ] - [-AttackSurfaceReductionOnlyExclusions ] [-ControlledFolderAccessAllowedApplications ] - [-ControlledFolderAccessProtectedFolders ] [-AttackSurfaceReductionRules_Ids ] - [-AttackSurfaceReductionRules_Actions ] [-EnableLowCpuPriority ] - [-EnableFileHashComputation ] [-EnableFullScanOnBatteryPower ] [-ProxyPacUrl ] - [-ProxyServer ] [-ProxyBypass ] [-ForceUseProxyOnly ] - [-OobeEnableRtpAndSigUpdate ] - [-DisableTlsParsing ] [-DisableHttpParsing ] [-DisableDnsParsing ] - [-DisableFtpParsing ] [-DisableSmtpParsing ] - [-DisableDnsOverTcpParsing ] [-DisableSshParsing ] +Set-MpPreference + [-AllowDatagramProcessingOnWinServer ] + [-AllowNetworkProtectionDownLevel ] + [-AllowNetworkProtectionOnWinServer ] + [-AllowSwitchToAsyncInspection ] + [-AsJob] + [-AttackSurfaceReductionOnlyExclusions ] + [-AttackSurfaceReductionRules_Actions ] + [-AttackSurfaceReductionRules_Ids ] + [-CheckForSignaturesBeforeRunningScan ] + [-CimSession ] + [-CloudBlockLevel ] + [-CloudExtendedTimeout ] + [-ControlledFolderAccessAllowedApplications ] + [-ControlledFolderAccessProtectedFolders ] + [-DefinitionUpdatesChannel ] + [-DisableArchiveScanning ] + [-DisableAutoExclusions ] + [-DisableBehaviorMonitoring ] + [-DisableBlockAtFirstSeen ] + [-DisableCacheMaintenance ] + [-DisableCatchupFullScan ] + [-DisableCatchupQuickScan ] + [-DisableCpuThrottleOnIdleScans ] + [-DisableDatagramProcessing ] + [-DisableDnsOverTcpParsing ] + [-DisableDnsParsing ] + [-DisableEmailScanning ] + [-DisableFtpParsing ] + [-DisableGradualRelease ] + [-DisableHttpParsing ] + [-DisableInboundConnectionFiltering ] + [-DisableIOAVProtection ] [-DisableNetworkProtectionPerfTelemetry ] - [-PlatformUpdatesChannel ] [-EngineUpdatesChannel ] - [-SignaturesUpdatesChannel ] [-DisableGradualRelease ] - [-AllowNetworkProtectionDownLevel ] [-AllowDatagramProcessingOnWinServer ] - [-EnableDnsSinkhole ] [-DisableInboundConnectionFiltering ] [-DisableRdpParsing ] - [-CimSession ] [-ThrottleLimit ] [-AsJob] [] + [-DisablePrivacyMode ] + [-DisableRdpParsing ] + [-DisableRealtimeMonitoring ] + [-DisableRemovableDriveScanning ] + [-DisableRestorePoint ] + [-DisableScanningMappedNetworkDrivesForFullScan ] + [-DisableScanningNetworkFiles ] + [-DisableScriptScanning ] + [-DisableSmtpParsing ] + [-DisableSshParsing ] + [-DisableTlsParsing ] + [-EnableControlledFolderAccess ] + [-EnableConvertWarnToBlock ] + [-EnableDnsSinkhole ] + [-EnableFileHashComputation ] + [-EnableFullScanOnBatteryPower ] + [-EnableLowCpuPriority ] + [-EnableNetworkProtection ] + [-EnableUdpReceiveOffload ] + [-EnableUdpSegmentationOffload ] + [-EngineUpdatesChannel ] + [-ExclusionExtension ] + [-ExclusionIpAddress ] + [-ExclusionPath ] + [-ExclusionProcess ] + [-Force] + [-ForceUseProxyOnly ] + [-HighThreatDefaultAction ] + [-IntelTDTEnabled ] + [-LowThreatDefaultAction ] + [-MAPSReporting ] + [-MeteredConnectionUpdates ] + [-ModerateThreatDefaultAction ] + [-OobeEnableRtpAndSigUpdate ] + [-PlatformUpdatesChannel ] + [-ProxyBypass ] + [-ProxyPacUrl ] + [-ProxyServer ] + [-PUAProtection ] + [-QuarantinePurgeItemsAfterDelay ] + [-RandomizeScheduleTaskTimes ] + [-RealTimeScanDirection ] + [-RemediationScheduleDay ] + [-RemediationScheduleTime ] + [-ReportingAdditionalActionTimeOut ] + [-ReportingCriticalFailureTimeOut ] + [-ReportingNonCriticalTimeOut ] + [-ScanAvgCPULoadFactor ] + [-ScanOnlyIfIdleEnabled ] + [-ScanParameters ] + [-ScanPurgeItemsAfterDelay ] + [-ScanScheduleDay ] + [-ScanScheduleOffset ] + [-ScanScheduleQuickScanTime ] + [-ScanScheduleTime ] + [-SchedulerRandomizationTime ] + [-ServiceHealthReportInterval ] + [-SevereThreatDefaultAction ] + [-SharedSignaturesPath ] + [-SignatureAuGracePeriod ] + [-SignatureBlobFileSharesSources ] + [-SignatureBlobUpdateInterval ] + [-SignatureDefinitionUpdateFileSharesSources ] + [-SignatureDisableUpdateOnStartupWithoutEngine ] + [-SignatureFallbackOrder ] + [-SignatureFirstAuGracePeriod ] + [-SignatureScheduleDay ] + [-SignatureScheduleTime ] + [-SignatureUpdateCatchupInterval ] + [-SignatureUpdateInterval ] + [-SubmitSamplesConsent ] + [-ThreatIDDefaultAction_Actions ] + [-ThreatIDDefaultAction_Ids ] + [-ThrottleForScheduledScanOnly ] + [-ThrottleLimit ] + [-UILockdown ] + [-UnknownThreatDefaultAction ] + [] ``` ## DESCRIPTION + The **Set-MpPreference** cmdlet configures preferences for Windows Defender scans and updates. -You can modify exclusion file name extensions, paths, or processes, and specify the default action for high, moderate, and low threat levels. +You can modify exclusion file name extensions, paths, or processes, and specify the default action +for high, moderate, and low threat levels. -**REMEDIATION VALUES** +**REMEDIATION VALUES**: -The following table provides remediation action values for detected threats at low, medium, high, and severe alert levels. +The following table provides remediation action values for detected threats at low, medium, high, +and severe alert levels. -|Value |Action | -|------|-------------------------------------------------------------------------| -|1 |Clean the detected threat. | -|2 |Quarantine the detected threat. | -|3 |Remove the detected threat. | -|6 |Allow the detected threat. | -|8 |Allow the user to determine the action to take with the detected threat. | -|9 |Don't take any action. | -|10 |Block the detected threat. | -|0 | (NULL)|Apply action based on the Security Intelligence Update (SIU). This is the default value. | +|Value|Action| +|---|---| +|0 (NULL)|Apply action based on the Security Intelligence Update (SIU). This is the default value.| +|1|Clean the detected threat.| +|2|Quarantine the detected threat.| +|3|Remove the detected threat.| +|6|Allow the detected threat.| +|8|Allow the user to determine the action to take with the detected threat.| +|9|Don't take any action.| +|10|Block the detected threat.| ## EXAMPLES ### Example 1: Schedule to check for definition updates everyday -```sql +```powershell PS C:\> Set-MpPreference -SignatureScheduleDay Everyday ``` @@ -99,16 +169,21 @@ This command configures preferences to check for definition updates every day. ### Example 2: Schedule a time of day to check for definition updates -```sql +```powershell PS C:\> Set-MpPreference -SignatureScheduleTime 02:00:00 ``` -This command configures preferences to check for definition updates 120 minutes after midnight on days when it's scheduled to check. +This command configures preferences to check for definition updates 120 minutes after midnight on +days when it's scheduled to check. ## PARAMETERS ### -AllowDatagramProcessingOnWinServer -Specifies whether to disable inspection of UDP connections on Windows Server. + +Specifies whether to disable the inspection of UDP connections on Windows Server. Valid values are: + +- $true: The inspection of UDP connections is enabled. +- $false: The inspection of UDP connections is disabled. ```yaml Type: Boolean @@ -123,7 +198,20 @@ Accept wildcard characters: False ``` ### -AllowNetworkProtectionDownLevel -Specifies whether to allow network protection to be set to Enabled or Audit Mode on Windows versions before 1709. + +Specifies whether network protection on Windows Server 2016 or Windows Server 2012 R2 is controlled +by the **EnableNetworkProtection** parameter. Valid values are: + +- $true: Network protection is controlled by the **EnableNetworkProtection** +parameter (Enabled, Disabled, or AuditMode). + + **Tip**: For Windows Server 2016 or Windows Server 2012 R2, you also need to set the +**AllowNetworkProtectionOnWinServer** parameter to the value $true. + +- $false: Network protection isn't controlled by the **EnableNetworkProtection** +parameter. + +For more information about network protection, see [Protect your network](/defender-endpoint/network-protection). ```yaml Type: Boolean @@ -138,7 +226,20 @@ Accept wildcard characters: False ``` ### -AllowNetworkProtectionOnWinServer -Specifies whether to allow network protection to be set to Enabled or Audit Mode for Windows Server. + +Specifies whether network protection on Windows Server is controlled by the +**EnableNetworkProtection** parameter. Valid values are: + +- $true: Network protection is controlled by the **EnableNetworkProtection** +parameter (Enabled, Disabled, or AuditMode). + + **Tip**: For Windows Server 2016 or Windows Server 2012 R2, you also need to set the +**AllowNetworkProtectionDownLevel** parameter to the value $true. + +- $false: Network protection isn't controlled by the **EnableNetworkProtection** +parameter. + +For more information about network protection, see [Protect your network](/defender-endpoint/network-protection). ```yaml Type: Boolean @@ -152,15 +253,20 @@ Accept pipeline input: False Accept wildcard characters: False ``` - ### -AllowSwitchToAsyncInspection -Specifies whether to enable a performance optimization that allows synchronously inspected network flows to switch to async inspection once they have been checked and validated. +Specifies whether to enable a performance optimization that allows synchronously inspected network +flows to switch to async inspection once they have been checked and validated. Valid values are: + +- $true: Allow synchronously inspected network flows to switch to async inspection once they have +been checked and validated. +- $false: Don't allow synchronously inspected network flows to switch to async inspection once they +have been checked and validated. ```yaml Type: Boolean Parameter Sets: (All) -Aliases: +Aliases: Required: False Position: Named @@ -169,16 +275,20 @@ Accept pipeline input: False Accept wildcard characters: False ``` - ### -AsJob -Runs the cmdlet as a background job. Use this parameter to run commands that take a long time to complete. -The cmdlet immediately returns an object that represents the job and then displays the command prompt. -You can continue to work in the session while the job completes. -To manage the job, use the `*-Job` cmdlets. -To get the job results, use the [Receive-Job](https://go.microsoft.com/fwlink/?LinkID=113372) cmdlet. +Runs the cmdlet as a background job. Use this parameter to run commands that take a long time to +complete. -For more information about Windows PowerShell background jobs, see [about_Jobs](https://go.microsoft.com/fwlink/?LinkID=113251). +The cmdlet immediately returns an object that represents the job and then displays the command +prompt. +You can continue to work in the session while the job completes. +To manage the job, use the `*-Job` cmdlets. +To get the job results, use the [Receive-Job](https://go.microsoft.com/fwlink/?LinkID=113372) +cmdlet. + +For more information about Windows PowerShell background jobs, see +[about_Jobs](https://go.microsoft.com/fwlink/?LinkID=113251). ```yaml Type: SwitchParameter @@ -193,9 +303,24 @@ Accept wildcard characters: False ``` ### -AttackSurfaceReductionOnlyExclusions -Specifies the files and paths to exclude from Attack Surface Reduction (ASR) rules. Specify the folders or files and resources that should be excluded from ASR rules. Enter a folder path or a fully qualified resource name. For example, ""C:\Windows"" will exclude all files in that directory. ""C:\Windows\App.exe"" will exclude only that specific file in that specific folder. -For more information about excluding files and folders from [ASR rules](/windows/security/threat-protection/microsoft-defender-atp/enable-attack-surface-reduction#exclude-files-and-folders-from-asr-rules). +Specifies the folders or files to exclude from Attack Surface Reduction (ASR) rules. Enter a folder +path or a fully qualified resource name. For example: + +- `"C:\Windows"` excludes all files in that folder. +- `"C:\Windows\App.exe"` excludes only that specific file in that specific folder. + +To replace all existing values with the values you specify, use the following syntax: `"Value1","Value2",..."ValueN"`. + +To add values without affecting existing values, use the **Add-MPPreference** cmdlet: + +`Add-MpPreference -AttackSurfaceReductionOnlyExclusions "Value1","Value2",..."ValueN"` + +To remove values without affecting other existing values, use the **Remove-MPPreference** cmdlet: + +`Remove-MpPreference -AttackSurfaceReductionOnlyExclusions "Value1","Value2",..."ValueN"` + +For more information, see [Exclude files and folders from attack surface reduction rules](/defender-endpoint/enable-attack-surface-reduction#exclude-files-and-folders-from-attack-surface-reduction-rules). ```yaml Type: String[] @@ -210,8 +335,36 @@ Accept wildcard characters: False ``` ### -AttackSurfaceReductionRules_Actions -Specifies the states of attack surface reduction rules specified by using the **AttackSurfaceReductionRules_Ids** parameter. -If you add multiple rules as a comma-separated list, specify their states separately as a comma-separated list. + +Use the **AttackSurfaceReductionRules_Ids** and **AttackSurfaceReductionRules_Actions** parameters +together in the same command to specify the states of attack surface reduction (ASR) rules. + +- The **AttackSurfaceReductionRules_Ids** parameter identifies the ASR rule by GUID value. For +example, the GUID value of the "Block Office communication application from creating child +processes" ASR rule is `26190899-1602-49e8-8b27-eb1d0a1ce869`. For more information, see +[ASR rule to GUID matrix](/defender-endpoint/attack-surface-reduction-rules-reference#asr-rule-to-guid-matrix). +- The **AttackSurfaceReductionRules_Actions** parameter identifies ASR rule action. Valid values +are: + + • 0 or Deactivated + + • 1 or Activated + + • 2 or Audit mode + + • 6 or Warning + +To replace all existing values with the values you specify, use the following syntax: + +`Set-MpPreference -AttackSurfaceReductionRules_Ids Rule1,Rule2,...RuleN -AttackSurfaceReductionRules_Actions Action1,Action2,...ActionN` + +To add values without affecting existing values, use the **Add-MPPreference** cmdlet: + +`Add-MpPreference -AttackSurfaceReductionRules_Ids Rule1,Rule2,...RuleN -AttackSurfaceReductionRules_Actions Action1,Action2,...ActionN` + +To remove values without affecting other existing values, use the **Remove-MPPreference** cmdlet: + +`Remove-MpPreference -AttackSurfaceReductionRules_Ids Rule1,Rule2,...RuleN -AttackSurfaceReductionRules_Actions Action1,Action2,...ActionN` ```yaml Type: ASRRuleActionType[] @@ -226,13 +379,43 @@ Accept wildcard characters: False ``` ### -AttackSurfaceReductionRules_Ids -Specifies the states of attack surface reduction rules specified by using the **AttackSurfaceReductionRules_Ids** parameter. -If you add multiple rules as a comma-separated list, specify their states separately as a comma-separated list. + +Use the **AttackSurfaceReductionRules_Ids** and **AttackSurfaceReductionRules_Actions** parameters +together in the same command to specify the states of attack surface reduction (ASR) rules. + +- The **AttackSurfaceReductionRules_Ids** parameter identifies the ASR rule by GUID value. For +example, the GUID value of the "Block Office communication application from creating child +processes" ASR rule is `26190899-1602-49e8-8b27-eb1d0a1ce869`. For more information, see +[ASR rule to GUID matrix](/defender-endpoint/attack-surface-reduction-rules-reference#asr-rule-to-guid-matrix). +- The **AttackSurfaceReductionRules_Actions** parameter identifies ASR rule action for the +- corresponding ASR rule. Valid values are: + + • 0 or Disabled + + • 1 or Enabled + + • 2 or AuditMode + + • 5 or NotConfigured + + • 6 or Warn + +To replace all existing values with the values you specify, use the following syntax: + +`Set-MpPreference -AttackSurfaceReductionRules_Ids Rule1,Rule2,...RuleN -AttackSurfaceReductionRules_Actions Action1,Action2,...ActionN` + +To add values without affecting existing values, use the **Add-MPPreference** cmdlet: + +`Add-MpPreference -AttackSurfaceReductionRules_Ids Rule1,Rule2,...RuleN -AttackSurfaceReductionRules_Actions Action1,Action2,...ActionN` + +To remove values without affecting other existing values, use the **Remove-MPPreference** cmdlet: + +`Remove-MpPreference -AttackSurfaceReductionRules_Ids Rule1,Rule2,...RuleN -AttackSurfaceReductionRules_Actions Action1,Action2,...ActionN` ```yaml Type: String[] Parameter Sets: (All) -Aliases: +Aliases: Required: False Position: Named @@ -242,10 +425,15 @@ Accept wildcard characters: False ``` ### -CheckForSignaturesBeforeRunningScan -Indicates whether to check for new virus and spyware definitions before Windows Defender runs a scan. -If you specify a value of $True, Windows Defender checks for new definitions. -If you specify $False or don't specify a value, the scan begins with existing definitions. -This setting applies to scheduled scans, but it has no effect on scans initiated manually from the user interface or on scans started from the command line using "mpcmdrun -Scan". + +Specifies whether to check for new virus and spyware definitions before Windows Defender runs a +scan. Valid values are: + +- $true: Windows Defender checks for new definitions before running a scan. +- $false: The scan begins with the existing definitions. This is the default value. + +This parameter applies to scheduled scans, but it has no effect on scans initiated manually from the +user interface from the command line using `mpcmdrun -Scan`. ```yaml Type: Boolean @@ -260,9 +448,16 @@ Accept wildcard characters: False ``` ### -CimSession -Runs the cmdlet in a remote session or on a remote computer. -Enter a computer name or a session object, such as the output of a [New-CimSession](https://go.microsoft.com/fwlink/p/?LinkId=227967) or [Get-CimSession](https://go.microsoft.com/fwlink/p/?LinkId=227966) cmdlet. -The default is the current session on the local computer. + +Runs the cmdlet in a remote session or on a remote computer that were created by the +[New-CimSession](https://go.microsoft.com/fwlink/p/?LinkId=227967) cmdlet and specified by the +[Get-CimSession](https://go.microsoft.com/fwlink/p/?LinkId=227966) cmdlet. For example: + +`Set-MpPreference -CimSession (Get-CimSession -ID 1),(Get-CimSession -ID 2),...(Get-CimSession -ID N)` + +or + +`Set-MpPreference -CimSession (Get-CimSession -ID Server1),(Get-CimSession -ID Server2),...(Get-CimSession -ID ServerN)` ```yaml Type: CimSession[] @@ -277,8 +472,15 @@ Accept wildcard characters: False ``` ### -CloudBlockLevel -Specifies a cloud block level. -This value determines how aggressive Microsoft Defender Antivirus is in blocking and scanning suspicious files. + +Specifies the cloud block level that determines how aggressively Microsoft Defender Antivirus scans +and blocks suspicious files. Valid values are: + +- 0 or Default +- 1 or Moderate +- 2 or High +- 4 or HighPlus +- 6 or ZeroTolerance ```yaml Type: CloudBlockLevelType @@ -293,7 +495,11 @@ Accept wildcard characters: False ``` ### -CloudExtendedTimeout -Specifies the amount of extended time to block a suspicious file and scan it in the cloud. Standard time is 10 seconds. Extend by up to 50 seconds. + + + +Specifies the amount of extended time in seconds to block a suspicious file and scan it in the +cloud. A valid value is an integer from 0 to 4294967295. The default value is 10 seconds. ```yaml Type: UInt32 @@ -308,7 +514,30 @@ Accept wildcard characters: False ``` ### -ControlledFolderAccessAllowedApplications -Specifies applications that can make changes in controlled folders. + +Specifies the path and filename of applications that are allowed to make changes in controlled +folders. You can use absolute folder paths (for example `C;\Windows\...` or environment variables +(for example, `%appdata%...`) for path names. + +To replace all existing values with the values you specify, use the following syntax: +`"PathAndFileName1","PathAndFileName2",..."PathAndFileNameN"`. + +To add values without affecting existing values, use the **Add-MPPreference** cmdlet: + +`Add-MpPreference -ControlledFolderAccessAllowedApplications "PathAndFileName1","PathAndFileName2",..."PathAndFileNameN"` + +To remove values without affecting other existing values, use the **Remove-MPPreference** cmdlet: + +`Remove-MpPreference -ControlledFolderAccessAllowedApplications "PathAndFileName1","PathAndFileName2",..."PathAndFileNameN"` + +The value parameter is meaningful only if the value of the **EnableControlledFolderAccess** +parameter isn't `Disabled`. + +To specify additional folders that are protected by controlled folder access, use the +**ControlledFolderAccessProtectedFolders** parameter. + +For more information about controlled folder access, see [Protect important folders with controlled +folder access](/defender-endpoint/controlled-folders). ```yaml Type: String[] @@ -323,7 +552,30 @@ Accept wildcard characters: False ``` ### -ControlledFolderAccessProtectedFolders -Specifies more folders to protect. + +Specifies additional folders to protect as controlled access folders. You can use absolute folder +paths (for example `C;\Windows\...` or environment variables (for example, `%appdata%...`) for path +names. + +To replace all existing values with the values you specify, use the following syntax: +`"Path1","Path2"..."PathN"`. + +To add values without affecting existing values, use the **Add-MPPreference** cmdlet: + +`Add-MpPreference -ControlledFolderAccessAllowedApplications "Path1","Path2",..."PathN"` + +To remove values without affecting other existing values, use the **Remove-MPPreference** cmdlet: + +`Remove-MpPreference -ControlledFolderAccessAllowedApplications "Path1","Path2",..."PathN"` + +The value parameter is meaningful only if the value of the **EnableControlledFolderAccess** +parameter isn't `Disabled`. + +To specify applications that are allowed to access controlled folders, use the +**ControlledFolderAccessAllowedApplications** parameter. + +For more information about controlled folder access, see [Protect important folders with controlled +folder access](/defender-endpoint/controlled-folders). ```yaml Type: String[] @@ -337,9 +589,40 @@ Accept pipeline input: False Accept wildcard characters: False ``` +### -DefinitionUpdatesChannel + +Specifies when devices receive daily Microsoft Defender definition updates during the monthly gradual +rollout. Valid values are: + +- NotConfigured: Devices stay up to date automatically during the gradual release cycle. This value +is suitable for most devices. +- Staged: Devices are offered updates after the monthly gradual release cycle. This value is +suggested for a small, representative part of your production population, around 10 percent. +- Broad: Devices are offered updates only after the gradual release cycle completes. This value is +suggested for a broad set of devices in your production population, from 10 to 100 percent. + +This parameter replaces the **SignaturesUpdatesChannel** parameter. + +```yaml +Type: DefinitionUpdatesChannelType +Parameter Sets: (All) +Aliases: duc +Accepted values: NotConfigured, Staged, Broad + +Required: False +Position: Named +Default value: None +Accept pipeline input: False +Accept wildcard characters: False +``` + ### -DisableArchiveScanning -Indicates whether to scan archive files, such as .zip and .cab files, for malicious and unwanted software. -If you specify a value of $False or do not specify a value, Windows Defender scans archive files. + +Specifies whether to scan archive files (for example, .zip and .cab files) for malicious and +unwanted software. Valid values are: + +- $true: Windows Defender doesn't scan archive file. +- $false: Windows Defender scans archive files. This is the default value. ```yaml Type: Boolean @@ -354,8 +637,11 @@ Accept wildcard characters: False ``` ### -DisableAutoExclusions -Indicates whether to disable the Automatic Exclusions feature for the server. -If you specify a value of $False or do not specify a value, Windows Defender enables the Automatic Exclusions feature for the server. + +Specifies whether to disable the Automatic Exclusions feature for the server. Valid values are: + +- $true: Windows Defender disables the Automatic Exclusions feature for the server. +- $false: Windows Defender enables the Automatic Exclusions feature for the server. This is the default value. ```yaml Type: Boolean @@ -370,8 +656,11 @@ Accept wildcard characters: False ``` ### -DisableBehaviorMonitoring -Indicates whether to enable behavior monitoring. -If you specify a value of $False or do not specify a value, Windows Defender enables behavior monitoring. + +Specifies whether to enable behavior monitoring. Valid values are: + +- $true: Windows Defender disables behavior monitoring. +- $false: Windows Defender enables behavior monitoring. This is the default value. ```yaml Type: Boolean @@ -386,8 +675,11 @@ Accept wildcard characters: False ``` ### -DisableBlockAtFirstSeen -Indicates whether to enable block at first seen. -If you specify a value of $False or do not specify a value, Windows Defender enables block at first seen. + +Specifies whether to enable block at first seen. Valid values are: + +- $true: Windows Defender disables block at first seen. +- $false: Windows Defender enables block at first seen. This is the default value. ```yaml Type: Boolean @@ -402,7 +694,11 @@ Accept wildcard characters: False ``` ### -DisableCacheMaintenance -Defines whether the cache maintenance idle task will perform the cache maintenance or not. Allowed values are 1 - cache maintenance is disabled, and 0 - cache maintenance is enabled (default). + +Defines whether the cache maintenance idle task performs cache maintenance. Valid values are: + +- $true: Cache maintenance is disabled. +- $false: Cache maintenance is enabled. This is the default value. ```yaml Type: Boolean @@ -411,15 +707,19 @@ Aliases: dcm Required: False Position: Named -Default value: 0 +Default value: 0 Accept pipeline input: False Accept wildcard characters: False ``` ### -DisableCatchupFullScan -Indicates whether Windows Defender runs catch-up scans for scheduled full scans. -A computer can miss a scheduled scan, usually because the computer is turned off at the scheduled time. -If you specify a value of $False, after the computer misses two scheduled full scans, Windows Defender runs a catch-up scan the next time someone logs on to the computer. If you specify a value of $True, the computer does not run catch-up scans for scheduled full scans. + +Specifies whether Windows Defender runs catch-up scans for missed scheduled full scans. Valid values +are: + +- $true: Windows Defender doesn't run catch-up scans for missed scheduled full scans. +- $false: After two missed scheduled full scans, Windows Defender runs a catch-up scan. +the next time someone signs in to the computer. ```yaml Type: Boolean @@ -428,15 +728,19 @@ Aliases: dcfsc Required: False Position: Named -Default value: 0 +Default value: 0 Accept pipeline input: False Accept wildcard characters: False ``` ### -DisableCatchupQuickScan -Indicates whether Windows Defender runs catch-up scans for scheduled quick scans. -A computer can miss a scheduled scan, usually because the computer is off at the scheduled time. -If you specify a value of $False, after the computer misses two scheduled quick scans, Windows Defender runs a catch-up scan the next time someone logs onto the computer. If you specify a value of $True, the computer does not run catch-up scans for scheduled quick scans. + +Specifies whether Windows Defender runs catch-up scans for missed scheduled quick scans. Valid values +are: + +$true: Windows Defender doesn't run catch-up scans for missed scheduled quick scans. +$false: After two missed scheduled quick scans, Windows Defender runs a catch-up scan +the next time someone signs in to the computer. ```yaml Type: Boolean @@ -451,7 +755,15 @@ Accept wildcard characters: False ``` ### -DisableCpuThrottleOnIdleScans -Indicates whether the CPU will be throttled for scheduled scans while the device is idle. This parameter is enabled by default, thus ensuring that the CPU won't be throttled for scheduled scans performed when the device is idle, regardless of what **ScanAvgCPULoadFactor** is set to. For all other scheduled scans, this flag does not have any impact and normal throttling will occur. + +Specifies whether the CPU is throttled for scheduled scans while the device is idle. Valid +values are: + +- $true: The CPU is throttled for scheduled scans. +- $false: The CPU isn't throttled for scheduled scans, regardless of the value of the +**ScanAvgCPULoadFactor** parameter. + +This parameter doesn't affect other types scheduled scans. Normal CPU throttling occurs on other types of scheduled scans. ```yaml Type: Boolean @@ -465,7 +777,11 @@ Accept wildcard characters: False ``` ### -DisableDatagramProcessing -Specifies whether to disable inspection of UDP connections. + +Specifies whether to disable inspection of UDP connections. Valid values are: + +- $true: Inspection of UDP connections is disabled. +- $false: Inspection of UDP connections is enabled. ```yaml Type: Boolean @@ -480,7 +796,19 @@ Accept wildcard characters: False ``` ### -DisableDnsOverTcpParsing -Specifies whether to disable inspection of DNS traffic that occurs over a TCP channel. + +Specifies whether to disable inspection of DNS traffic that occurs over a TCP. Valid values +are: + +- $true: Inspection of DNS traffic over TCP is disabled. +- $false: Inspection of DNS traffic over TCP is enabled. + +Network protection needs to inspect DNS traffic over TCP in the following scenarios: + +- To provide metadata for anti-malware behavior monitoring. +- To allow for a DNS sinkhole if the **EnableDnsSinkhole** parameter is set to the value $true. + +For more information about network protection, see [Protect your network](/defender-endpoint/network-protection). ```yaml Type: Boolean @@ -495,8 +823,12 @@ Accept wildcard characters: False ``` ### -DisableDnsParsing -Specifies whether to disable inspection of DNS traffic that occurs over a UDP channel. -Network protection inspects DNS traffic that occurs over a TCP channel to provide metadata for anti-malware behavior monitoring or to allow for DNS sink holing if the "-EnableDnsSinkhole" configuration is set. This can be disabled by setting this value to "$true". + +Specifies whether to disable inspection of DNS traffic that occurs over a UDP. Valid values +are: + +- $true: Inspection of DNS traffic over UDP is disabled. +- $false: Inspection of DNS traffic over UDP channels is enabled. ```yaml Type: Boolean @@ -510,48 +842,68 @@ Accept pipeline input: False Accept wildcard characters: False ``` -### -DisableFtpParsing -Specifies whether to disable FTP parsing for network protection. +### -DisableEmailScanning + +Specifies whether Windows Defender parses mailbox and email message files to analyze message bodies +and email attachments. Valid values are: + +- $true: Windows Defender doesn't scan mailbox and email message files. +- $false: Windows Defender scans mailbox and email message files. This is the default value. + + Windows Defender supports several mailbox and email message file formats. For example: + +- .binhex +- .dbx +- .mbx +- .mime +- .pst ```yaml Type: Boolean Parameter Sets: (All) -Aliases: dfp +Aliases: demsc Required: False Position: Named -Default value: 0 +Default value: None Accept pipeline input: False Accept wildcard characters: False ``` -### -DisableEmailScanning -Indicates whether Windows Defender parses the mailbox and mail files, according to their specific format, in order to analyze mail bodies and attachments. -Windows Defender supports several formats, including .pst, .dbx, .mbx, .mime, and .binhex. -If you specify a value of $False or do not specify a value, Windows Defender performs email scanning. If you specify a value of $True, Windows Defender does not perform email scanning. +### -DisableFtpParsing + +Specifies whether to disable FTP parsing for network protection. Valid values are: + +- $true: FTP parsing for network protection is disabled. +- $false: FTP parsing for network protection is enabled. + +For more information about network protection, see [Protect your network](/defender-endpoint/network-protection). ```yaml Type: Boolean Parameter Sets: (All) -Aliases: demsc +Aliases: dfp Required: False Position: Named -Default value: None +Default value: 0 Accept pipeline input: False Accept wildcard characters: False ``` ### -DisableGradualRelease -Specifies whether to disable gradual rollout of monthly and daily Windows Defender updates. -If you enable this option, devices are offered all updates after the gradual release cycle finishes. -Consider this option for datacenter computers that only receive limited updates. -This setting applies to both monthly and daily updates. -It overrides configured channel selections for platform and engine updates. +Specifies whether to disable gradual rollout of monthly and daily Windows Defender updates. Valid +values are: + +- $true: Devices are offered all updates after the gradual release cycle finishes. Consider this +option for datacenter computers that receive only limited updates. +- $false: This is the default value. Devices remain in the Current Channel unless otherwise +specified in specific channels. The device stays up to date automatically during the gradual release +cycle, which is suitable for most devices. -If you disable or do not configure this policy, the device remains in Current Channel (Default) unless specified otherwise in specific channels. -The device stays up to date automatically during the gradual release cycle, which is suitable for most devices. +This setting applies to both monthly and daily updates. This setting overrides configured channel +selections for platform and engine updates. This policy is available starting with platform version 4.18.2106.5 and later. @@ -568,8 +920,14 @@ Accept wildcard characters: False ``` ### -DisableHttpParsing -Specifies whether disable inspection of HTTP traffic. -If **EnableNetworkProtection** has the value `Enabled`, HTTP connections to malicious websites can be blocked. + +Specifies whether to disable inspection of HTTP traffic. Valid values are: + +- $true: Inspection of HTTP traffic is disabled. +- $false: Inspection of HTTP traffic is enabled. + +If the value of the **EnableNetworkProtection** parameter is `Enabled`, HTTP connections to +malicious websites can be blocked. ```yaml Type: Boolean @@ -584,8 +942,13 @@ Accept wildcard characters: False ``` ### -DisableInboundConnectionFiltering -Specifies whether to inspect only outbound connections. -By default, Network Protection inspects both inbound and outbound connections. + +Specifies whether Network Protection inspects only outbound connections. Valid values are: + +- $true: Network Protection inspects only outbound connections. +- $false: Network Protection inspects inbound and outbound connections. This is the default value. + +For more information about network protection, see [Protect your network](/defender-endpoint/network-protection). ```yaml Type: Boolean @@ -600,8 +963,11 @@ Accept wildcard characters: False ``` ### -DisableIOAVProtection -Indicates whether Windows Defender scans all downloaded files and attachments. -If you specify a value of $False or do not specify a value, scanning downloaded files and attachments is enabled. + +Specifies whether Windows Defender scans all downloaded files and attachments. Valid values are: + +- $true: Windows Defender doesn't scan all downloaded files and attachments. +- $false: Windows Defender scans all downloaded files and attachments. This is the default value. ```yaml Type: Boolean @@ -615,11 +981,15 @@ Accept pipeline input: False Accept wildcard characters: False ``` -### -DisableNetworkProtectionPerfTelemetry -This setting disables the gathering and sending of performance telemetry from network protection. -The accepted values are 0 and 1. -- 1- Network protection telemetry is disabled. -- 0 (Default) - Network protection telemetry is enabled. +### -DisableNetworkProtectionPerfTelemetry + +This setting disables the gathering and sending of performance telemetry from network protection. +Valid values are: + +- $true: Network protection telemetry is disabled. +- $false: Network protection telemetry is enabled. This is the default value. + +For more information about network protection, see [Protect your network](/defender-endpoint/network-protection). ```yaml Type: Boolean @@ -634,7 +1004,11 @@ Accept wildcard characters: False ``` ### -DisablePrivacyMode -**This is a legacy setting that does not have any affect on current platforms**. The intent of this parameter was to disable privacy mode, which prevented users, other than administrators, from displaying threat history. When this parameter was in use, if you specified a value of $False or did not specify a value, privacy mode was enabled. + +**Note**: This parameter is a legacy setting that doesn't affect current platforms. + +The intent of this parameter was to disable privacy mode, which prevented users (not admins) from +displaying the threat history. ```yaml Type: Boolean @@ -649,7 +1023,12 @@ Accept wildcard characters: False ``` ### -DisableRdpParsing -This setting controls whether to parse RDP traffic to look for malicious attacks using the RDP protocol. + +This setting controls whether to parse RDP traffic to look for malicious attacks using the RDP +protocol. Valid values are: + +- $true: Windows Defender doesn't scan RDP traffic. +- $false: Windows Defender scans RDP traffic. ```yaml Type: Boolean @@ -664,9 +1043,11 @@ Accept wildcard characters: False ``` ### -DisableRealtimeMonitoring -Indicates whether to use real-time protection. -If you specify a value of $False or do not specify a value, Windows Defender uses real-time protection. -We recommend that you enable Windows Defender to use real-time protection. + +Specifies whether to use real-time protection. Valid values are: + +- $true: Windows Defender doesn't use real-time protection. +- $false: Windows Defender uses real-time protection. This is the default and recommended value. ```yaml Type: Boolean @@ -681,8 +1062,14 @@ Accept wildcard characters: False ``` ### -DisableRemovableDriveScanning -Indicates whether to scan for malicious and unwanted software in removable drives, such as flash drives, during a full scan. -If you specify a value of $False or do not specify a value, Windows Defender scans removable drives during any type of scan. If you specify a value of $True, Windows Defender does not scan removable drives during a full scan. Windows Defender can still scan removable drives during quick scans or custom scans. + +Specifies whether to scan for malicious and unwanted software in removable drives, such as flash +drives, during a full scan. Valid values are: + +- $true: Windows Defender doesn't scan removable drives during a full scan, but can still scan +removable drives during quick scans or custom scans. +- $false: Windows Defender scans removable drives during any type of scan. This is the default +value. ```yaml Type: Boolean @@ -697,13 +1084,16 @@ Accept wildcard characters: False ``` ### -DisableRestorePoint -Indicates whether to disable scanning of restore points. -If you specify a value of $False or do not specify a value, Windows Defender restore point is enabled. + +Specifies whether to disable scanning of restore points. Valid values are: + +- $true: Windows Defender restore point scanning is disabled. +- $false: Windows Defender restore point scanning is enabled. This is the default value. ```yaml Type: Boolean Parameter Sets: (All) -Aliases: drp, dsnf +Aliases: drp Required: False Position: Named @@ -713,7 +1103,11 @@ Accept wildcard characters: False ``` ### -DisableScanningMappedNetworkDrivesForFullScan -Indicates whether to scan mapped network drives. If you specify a value of $False or do not specify a value, Windows Defender scans mapped network drives. If you specify a value of $True, Windows Defender does not scan mapped network drives. + +Specifies whether to scan mapped network drives. Valid values are: + +- $true: Windows Defender doesn't scan mapped network drives. +- $false: Windows Defender scans mapped network drives. This is the default value. ```yaml Type: Boolean @@ -728,7 +1122,11 @@ Accept wildcard characters: False ``` ### -DisableScanningNetworkFiles -Indicates whether to scan for network files. If you specify a value of $False or do not specify a value, Windows Defender scans network files. If you specify a value of $True, Windows Defender does not scan network files. + +Specifies whether to scan network files. Valid values are: + +- $true: Windows Defender doesn't scan network files. +- $false: Windows Defender scans network files. This is the default value. ```yaml Type: Boolean @@ -743,8 +1141,11 @@ Accept wildcard characters: False ``` ### -DisableScriptScanning -Specifies whether to disable the scanning of scripts during malware scans. -If you specify a value of $False or do not specify a value, Windows Defender does not scan scripts. + +Specifies whether to disable the scanning of scripts during malware scans. Valid values are: + +- $true: Windows Defender doesn't scan scripts. +- $false: Windows Defender scans scripts. This is the default value. ```yaml Type: Boolean @@ -758,43 +1159,62 @@ Accept pipeline input: False Accept wildcard characters: False ``` -### -DisableSshParsing -Specifies whether to disable inspection of SSH traffic. -By default, Network Protection inspects SSH traffic. +### -DisableSmtpParsing + +This setting disables SMTP parsing by network protection. Valid values are: + +- $true: SMTP parsing is disabled. +- $false: SMTP parsing is enabled. This is the default value + +For more information about network protection, see [Protect your network](/defender-endpoint/network-protection). ```yaml Type: Boolean Parameter Sets: (All) -Aliases: dsshp +Aliases: dsp Required: False Position: Named -Default value: None +Default value: 0 Accept pipeline input: False Accept wildcard characters: False ``` -### -DisableSmtpParsing -This setting disables SMTP parsing for network protection. -The accepted values are 0 and 1. -- 1 - SMTP parsing is disabled. -- 0 (Default) - SMTP parsing is enabled. +### -DisableSshParsing + +Specifies whether to disable the inspection of SSH traffic. Valid values are: + +- $true: Network protection doesn't inspect SSH traffic. +- $false: Network protection inspects SSH traffic. This is the default value. + +For more information about network protection, see [Protect your network](/defender-endpoint/network-protection). ```yaml Type: Boolean Parameter Sets: (All) -Aliases: dsp +Aliases: dsshp Required: False Position: Named -Default value: 0 +Default value: None Accept pipeline input: False Accept wildcard characters: False ``` ### -DisableTlsParsing -Specifies whether to disable inspection of TLS traffic. -Network protection inspects TLS traffic (also known as HTTPS traffic) to see if a connection is being made to a malicious website, and to provide metadata to behavior monitoring. TLS connections to malicious websites can also be blocked if "-EnableNetworkProtection" is set to enabled. HTTP inspection can be disabled by setting this value to "$true". By default, network protection inspects TLS traffic. + +Specifies whether to disable the inspection of TLS traffic. Valid values are: + +- $true: Network Protection doesn't inspect TLS traffic. +- $false: Network Protection inspects TLS traffic. This is the default value. + +Network protection inspects TLS traffic (also known as HTTPS traffic) to see if a connection is +being made to a malicious website, and to provide metadata to behavior monitoring. + +TLS connections to malicious websites can also be blocked if the value of the +**EnableNetworkProtection** parameter is `Enabled`. + +For more information about network protection, see [Protect your network](/defender-endpoint/network-protection). ```yaml Type: Boolean @@ -809,7 +1229,25 @@ Accept wildcard characters: False ``` ### -EnableControlledFolderAccess -Specifies the state for the controlled folder access feature. Valid values are Disabled, Enabled, and Audit Mode. + + + +Specifies the state for the controlled folder access feature. Valid values are: + +- Disabled +- Enabled +- AuditMode +- BlockDiskModificationOnly +- AuditDiskModificationOnly + +To specify additional folders that are protected by controlled folder access, use the +**ControlledFolderAccessProtectedFolders** parameter. + +To specify applications that are allowed to access controlled folders, use the +**ControlledFolderAccessAllowedApplications** parameter. + +For more information about controlled folder access, see [Protect important folders with controlled +folder access](/defender-endpoint/controlled-folders). ```yaml Type: ControlledFolderAccessType @@ -824,10 +1262,17 @@ Accept wildcard characters: False ``` ### -EnableConvertWarnToBlock -This setting controls whether network protection blocks network traffic instead of displaying a warning. This setting can be manually controlled by setting it to `1` to enable and `0` to disable. + +This setting controls whether network protection blocks network traffic instead of displaying a +warning. Valid values are: + +- $true: Network Protection blocks network traffic instead of displaying a warning. +- $false: Network Protection displaying a warning. + +For more information about network protection, see [Protect your network](/defender-endpoint/network-protection). ```yaml -Type: ASRRuleActionType +Type: Boolean Parameter Sets: (All) Aliases: @@ -838,9 +1283,19 @@ Accept pipeline input: False Accept wildcard characters: False ``` -### -EnableDnsSinkhole (Deprecated) -Specifies whether to examine DNS traffic to detect and sinkhole DNS exfiltration attempts and other DNS based malicious attacks. -Network protection can inspect the DNS traffic of a machine and, in conjunction with behavior monitoring, detect and sink hole DNS exfiltration attempts, and other DNS based malicious attacks. Set this configuration to "$true" to enable this feature. +### -EnableDnsSinkhole + +**Note**: This parameter has been deprecated. + +Specifies whether to examine DNS traffic to detect and sinkhole DNS exfiltration attempts and other +DNS based malicious attacks. Valid values are: + +- $true: DNS sinkhole is enabled. Network protection can inspect the DNS traffic of a machine and, +in conjunction with behavior monitoring, detect and sinkhole DNS exfiltration attempts, and other +DNS based malicious attacks. +- $false: DNS sinkhole is disabled. + +For more information about network protection, see [Protect your network](/defender-endpoint/network-protection). ```yaml Type: Boolean @@ -855,8 +1310,11 @@ Accept wildcard characters: False ``` ### -EnableFileHashComputation -Specifies whether to enable file hash computation. -When this feature is enabled, Windows Defender computes hashes for files it scans. + +Specifies whether to enable file hash computation. Valid values are: + +- $true: Windows Defender computes hashes for scanned files. +- $false: Windows Defender doesn't compute hashes for scanned files. ```yaml Type: Boolean @@ -871,7 +1329,11 @@ Accept wildcard characters: False ``` ### -EnableFullScanOnBatteryPower -Specifies whether Windows Defender does a full scan while on battery power. + +Specifies whether Windows Defender does full scans while on battery power. Valid values are: + +- $true: Windows Defender does full scans while on battery power. +- $false: Windows Defender doesn't do full scans while on battery power. ```yaml Type: Boolean @@ -886,7 +1348,11 @@ Accept wildcard characters: False ``` ### -EnableLowCpuPriority -Specifies whether Windows Defender uses low CPU priority for scheduled scans. + +Specifies whether Windows Defender uses low CPU priority for scheduled scans. Valid values are: + +- $true: Windows Defender uses low CPU priority for scheduled scans. +- $false: Windows Defender doesn't use low CPU priority for scheduled scans. ```yaml Type: Boolean @@ -901,8 +1367,19 @@ Accept wildcard characters: False ``` ### -EnableNetworkProtection -Specifies how the network protection service handles web-based malicious threats, including phishing and malware. -Possible values are Disabled, Enabled, and AuditMode. + +Specifies how the network protection service handles web-based malicious threats, including phishing +and malware. Valid values are: + +- 0 or Disabled +- 1 or Enabled +- 2 or AuditMode + +**Tip**: Network protection on Windows Server also requires that the +**AllowNetworkProtectionOnWinServer** and (for Windows Server 2016 or Windows Server 2012 R2) +**AllowNetworkProtectionDownLevel** parameters are set to the value $true. + +For more information about network protection, see [Protect your network](/defender-endpoint/network-protection). ```yaml Type: ASRRuleActionType @@ -916,11 +1393,19 @@ Accept pipeline input: False Accept wildcard characters: False ``` -### Enable UdpReceiveOffload: -Specifies whether UDP receive offload support in Network Protection is enabled, resulting in potentially higher UDP bandwidth in the inbound direction. Starting with platform version `4.18.24030`, Microsoft will gradually move this support default from disabled to enabled. This setting can be manually controlled by setting it to `1` to enable and `0` to disable. +### -EnableUdpReceiveOffload + +Specifies whether UDP receive offload support in Network Protection is enabled, resulting in +potentially higher inbound UDP bandwidth. Valid values are: + +- $true: UDP receive offload support in Network Protection is enabled. +- $false: UDP receive offload support in Network Protection is disabled. + +Starting with platform version `4.18.24030`, we're gradually moving the default value from +$false (disabled) to $true (enabled). ```yaml -Type: ASRRuleActionType +Type: Boolean Parameter Sets: (All) Aliases: @@ -931,11 +1416,19 @@ Accept pipeline input: False Accept wildcard characters: False ``` -### Enable UdpSegmentationOffload: -Specifies whether UDP segmentation offload support in Network Protection is enabled, resulting in potentially higher UDP bandwidth in the outbound direction. Starting with platform version `4.18.24030`, Microsoft will gradually move this support default from disabled to enabled. This setting can be manually controlled by setting it to `1` to enable and `0` to disable. +### -EnableUdpSegmentationOffload + +Specifies whether UDP segmentation offload support in Network Protection is enabled, resulting in +potentially higher outbound UDP bandwidth in the outbound direction. Valid values are: + +- $true: UDP segmentation offload support in Network Protection is enabled. +- $false: UDP segmentation offload support in Network Protection is disabled. + +Starting with platform version `4.18.24030`, Microsoft will gradually move the default value from +disabled to enabled. ```yaml -Type: ASRRuleActionType +Type: Boolean Parameter Sets: (All) Aliases: @@ -947,20 +1440,28 @@ Accept wildcard characters: False ``` ### -EngineUpdatesChannel -Specifies when devices receive Microsoft Defender engine updates during the monthly gradual rollout. -Valid values are: +Specifies when devices receive Microsoft Defender engine updates during the monthly gradual +rollout. Valid values are: -- NotConfigured. Devices stay up to date automatically during the gradual release cycle. This value is suitable for most devices. -- Beta. Devices are the first to receive new updates. Select Beta Channel to participate in identifying and reporting issues to Microsoft. Devices in the Windows Insider Program are subscribed to this channel by default. This value is for use in manual test environments only and a limited number of devices. -- Broad. Devices are offered updates only after the gradual release cycle completes. This value is suggested for a broad set of devices in your production population, from 10 to 100 percent. -- Preview. Devices are offered updates earliest during the monthly gradual release cycle. This value is suggested for pre-production or validation environments. -- Staged. Devices are offered updates after the monthly gradual release cycle. This value is suggested for a small, representative part of your production population, around 10 percent. +- 0 or NotConfigured: Devices stay up to date automatically during the gradual release cycle. This +value is suitable for most devices. +- 2 or Beta: Devices are the first to receive new updates. Select Beta Channel to participate in +identifying and reporting issues to Microsoft. Devices in the Windows Insider Program are +subscribed to this channel by default. This value is for use in manual test environments only and a +limited number of devices. +- 3 or Preview: Devices are offered updates earliest during the monthly gradual release cycle. This +value is suggested for pre-production or validation environments. +- 4 or Staged: Devices are offered updates after the monthly gradual release cycle. This value is +suggested for a small, representative part of your production population, around 10 percent. +- 5 or Broad: Devices are offered updates only after the gradual release cycle completes. This +value is suggested for a broad set of devices in your production population, from 10 to 100 percent. +- 6 or Delayed ```yaml Type: UpdatesChannelType Parameter Sets: (All) -Aliases: erelr +Aliases: euc Required: False Position: Named @@ -970,7 +1471,19 @@ Accept wildcard characters: False ``` ### -ExclusionExtension -Specifies an array of file name extensions, such as obj or lib, to exclude from scheduled, custom, and real-time scanning. + +Specifies the file name extensions, such as `obj` and `lib`, to exclude from scheduled, custom, +and real-time scanning. + +To replace all existing values with the values you specify, use the following syntax: `"Extension1","Extension2",..."ExtensionN"`. + +To add values without affecting existing values, use the **Add-MPPreference** cmdlet: + +`Add-MpPreference -ExclusionExtension "Extension1","Extension2"..."ExtensionN"` + +To remove values without affecting other existing values, use the **Remove-MPPreference** cmdlet: + +`Remove-MpPreference -ExclusionExtension "Extension1","Extension2"..."ExtensionN"` ```yaml Type: String[] @@ -985,12 +1498,23 @@ Accept wildcard characters: False ``` ### -ExclusionIpAddress -Specifies an array of IP addresses to exclude from scheduled and real-time scanning. + +Specifies the IP addresses to exclude from scheduled and real-time scanning. + +To replace all existing values with the values you specify, use the following syntax: `"IPAddress1","IPAddress2",..."IPAddresseN"`. + +To add values without affecting existing values, use the **Add-MPPreference** cmdlet: + +`Add-MpPreference -ExclusionIpAddress "IPAddress1","IPAddress",..."IPAddressN"` + +To remove values without affecting other existing values, use the **Remove-MPPreference** cmdlet: + +`Remove-MpPreference -ExclusionIpAddress "IPAddress1","IPAddress2",..."IPAddressN"` ```yaml Type: String[] Parameter Sets: (All) -Aliases: +Aliases: Required: False Position: Named @@ -1000,13 +1524,25 @@ Accept wildcard characters: False ``` ### -ExclusionPath -Specifies an array of file paths to exclude from scheduled and real-time scanning. -You can specify a folder to exclude all the files under the folder. + +Specifies the path and filename (for specific files) or path only (for all files in the folder) to +exclude from scheduled and real-time scanning. + +To replace all existing values with the values you specify, use the following syntax: +`"Value1","Value2"..."ValueN"`. + +To add values without affecting existing values, use the **Add-MPPreference** cmdlet: + +`Add-MpPreference -ExclusionPath "Value1","Value2",..."ValuehN"` + +To remove values without affecting other existing values, use the **Remove-MPPreference** cmdlet: + +`Remove-MpPreference -ExclusionPath "Value1","Value2",..."ValueN"` ```yaml Type: String[] Parameter Sets: (All) -Aliases: +Aliases: Required: False Position: Named @@ -1016,16 +1552,27 @@ Accept wildcard characters: False ``` ### -ExclusionProcess -Specifies an array of processes, as paths to process images. -This cmdlet excludes any files opened by the processes that you specify from scheduled and real-time scanning. -Specifying this parameter excludes files opened by executable programs only. -The cmdlet does not exclude the processes themselves. -To exclude a process, specify it by using the **ExclusionPath** parameter. + +Specifies the paths to process images to exclude from scheduled and real-time scanning. + +To replace all existing values with the values you specify, use the following syntax: +`"Path1","Path2"..."PathN"`. + +To add values without affecting existing values, use the **Add-MPPreference** cmdlet: + +`Add-MpPreference -ExclusionProcess "Path1","Path2",..."PathhN"` + +To remove values without affecting other existing values, use the **Remove-MPPreference** cmdlet: + +`Remove-MpPreference -ExclusionProcess "Path1","Path2",..."PathN"` + +This parameter excludes files opened by executable programs only, not the processes themselves. +To exclude processes, use the **ExclusionPath** parameter. ```yaml Type: String[] Parameter Sets: (All) -Aliases: +Aliases: Required: False Position: Named @@ -1035,7 +1582,9 @@ Accept wildcard characters: False ``` ### -Force -Forces the command to run without asking for user confirmation. + +Forces the command to run without asking for user confirmation. You don't need to specify a value +with this switch. ```yaml Type: SwitchParameter @@ -1050,7 +1599,11 @@ Accept wildcard characters: False ``` ### -ForceUseProxyOnly -Specifies whether to force the device to use only the proxy. + +Specifies whether to force the device to use only the proxy. Valid values are: + +- $true: Use the proxy only. +- $false: Don't force the device to use the proxy. ```yaml Type: Boolean @@ -1065,12 +1618,19 @@ Accept wildcard characters: False ``` ### -HighThreatDefaultAction -Specifies which automatic remediation action to take for a high level threat. -The acceptable values for this parameter are: -- Quarantine -- Remove -- Ignore + + +Specifies the automatic remediation action to take for high level threats. Valid values are: + +- Clean +- Quarantine +- Remove +- Allow +- UserDefined +- NoAction +- Block ```yaml Type: ThreatAction @@ -1086,14 +1646,15 @@ Accept wildcard characters: False ``` ### -IntelTDTEnabled -This policy setting configures the Intel TDT integration level for Intel TDT-capable devices. -The acceptable values for this parameter are: -- 0 (Default) - If you don't configure this setting, the default value will be applied. The default value is controlled by Microsoft security intelligence updates. Microsoft will enable Intel TDT if there is a known threat. -- 1 - If you configure this setting to enabled, Intel TDT integration will turn on. -- 2 - If you configure this setting to disabled, Intel TDT integration will turn off. + +This policy setting configures the Intel TDT integration level for Intel TDT-capable devices. Valid +values are: + +- $true: Intel TDT integration is turned on. +- $false: Intel TDT integration is turned off. ```yaml -Type: UInt32 +Type: Boolean Parameter Sets: (All) Aliases: itdte Accepted values: 0,1 and 2 @@ -1106,12 +1667,19 @@ Accept wildcard characters: False ``` ### -LowThreatDefaultAction -Specifies which automatic remediation action to take for a low level threat. -The acceptable values for this parameter are: + + +Specifies the automatic remediation action to take for low level threats. Valid values are: + +- Clean - Quarantine - Remove -- Ignore +- Allow +- UserDefined +- NoAction +- Block ```yaml Type: ThreatAction @@ -1127,28 +1695,27 @@ Accept wildcard characters: False ``` ### -MAPSReporting -Specifies the type of membership in Microsoft Active Protection Service. -Microsoft Active Protection Service is an online community that helps you choose how to respond to potential threats. -The community also helps prevent the spread of new malicious software. -The acceptable values for this parameter are: -- 0: Disabled. -Send no information to Microsoft. -This is the default value. -- 1: Basic membership. -Send basic information to Microsoft about detected software, including where the software came from, the actions that you apply or that apply automatically, and whether the actions succeeded. -- 2: Advanced membership. -In addition to basic information, send more information to Microsoft about malicious software, spyware, and potentially unwanted software, including the location of the software, file names, how the software operates, and how it affects your computer. +Specifies the type of membership in Microsoft Active Protection Service. This services is an online +community that helps you choose how to respond to potential threats. The community also helps +prevent the spread of new malicious software. Valid values are: + +- 0 or Disabled: Send no information to Microsoft. This is the default value. +- 1 or Basic: Send basic information to Microsoft about detected software, including where the software +came from, the actions you applied (manually or automatically), and whether the actions succeeded. +- 2 or Advanced: In addition to basic information, send more information to Microsoft about malicious +software, spyware, and potentially unwanted software, including the location of the software, +filenames, how the software operates, and how it affects your computer. -If you join this community, you can choose to automatically send basic or additional information about detected software. -Additional information helps Microsoft create new definitions. -In some instances, personal information might unintentionally be sent to Microsoft. -However, Microsoft will not use this information to identify you or contact you. +If you join this community, you can choose to automatically send basic or additional information +about detected software. Additional information helps Microsoft create new definitions. In some +instances, personal information might unintentionally be sent to Microsoft. However, Microsoft +doesn't use this information to identify you or contact you. ```yaml Type: MAPSReportingType Parameter Sets: (All) -Aliases: +Aliases: Accepted values: Disabled, Basic, Advanced Required: False @@ -1159,8 +1726,11 @@ Accept wildcard characters: False ``` ### -MeteredConnectionUpdates -Specifies whether to update managed devices to update through metered connections. -Data charges may apply. + +Specifies whether to update managed devices to update through metered connections. Valid values are: + +- $true: Updates are made over metered connections. Data charges may apply. +- $false: Updates aren't made over metered connections. ```yaml Type: Boolean @@ -1175,12 +1745,19 @@ Accept wildcard characters: False ``` ### -ModerateThreatDefaultAction -Specifies which automatic remediation action to take for a moderate level threat. -The acceptable values for this parameter are: -- Quarantine -- Remove -- Ignore + + +Specifies the automatic remediation action to take for moderate level threats. Valid values are: + +- Clean +- Quarantine +- Remove +- Allow +- UserDefined +- NoAction +- Block ```yaml Type: ThreatAction @@ -1197,16 +1774,17 @@ Accept wildcard characters: False ### -OobeEnableRtpAndSigUpdate -This setting allows you to configure whether real-time protection and Security Intelligence Updates are enabled during Out of Box experience (OOBE). +This setting allows you to configure whether real-time protection and Security Intelligence Updates +are enabled during Out of Box experience (OOBE). Valid values are: -Valid values are: -- True - If you enable this setting, real-time protection and Security Intelligence Updates are enabled during OOBE. -- False (Default) - If you either disable or don't configure this setting, real-time protection and Security Intelligence Updates during OOBE aren't enabled. +- $true: Real-time protection and Security Intelligence Updates are enabled during OOBE. +- $false: Real-time protection and Security Intelligence Updates during OOBE aren't enabled. This +is the default value. ```yaml Type: Boolean Parameter Sets: (All) -Aliases: +Aliases: Required: False Position: Named @@ -1216,15 +1794,23 @@ Accept wildcard characters: False ``` ### -PlatformUpdatesChannel -Specifies when devices receive Microsoft Defender platform updates during the monthly gradual rollout. -Valid values are: +Specifies when devices receive Microsoft Defender platform updates during the monthly gradual +rollout. Valid values are: -- NotConfigured. Devices stay up to date automatically during the gradual release cycle. This value is suitable for most devices. -- Beta. Devices are the first to receive new updates. Select Beta Channel to participate in identifying and reporting issues to Microsoft. Devices in the Windows Insider Program are subscribed to this channel by default. This value is for use in manual test environments only and a limited number of devices. -- Broad. Devices are offered updates only after the gradual release cycle completes. This value is suggested for a broad set of devices in your production population, from 10 to 100 percent. -- Preview. Devices are offered updates earliest during the monthly gradual release cycle. This value is suggested for pre-production or validation environments. -- Staged. Devices are offered updates after the monthly gradual release cycle. This value is suggested for a small, representative part of your production population, around 10 percent. +- NotConfigured: Devices stay up to date automatically during the gradual release cycle. This value +is suitable for most devices. +- Beta: Devices are the first to receive new updates. Select Beta Channel to participate in +identifying and reporting issues to Microsoft. Devices in the Windows Insider Program are +subscribed to this channel by default. This value is for use in manual test environments only and +for a limited number of devices. +- Preview: Devices are offered updates earliest during the monthly gradual release cycle. This value +is suggested for pre-production or validation environments. +- Staged: Devices are offered updates after the monthly gradual release cycle. This value is +suggested for a small, representative part of your production population, around 10 percent. +- Broad: Devices are offered updates only after the gradual release cycle completes. This value is +suggested for a broad set of devices in your production population, from 10 to 100 percent. +- Delayed ```yaml Type: UpdatesChannelType @@ -1239,8 +1825,38 @@ Accept wildcard characters: False ``` ### -ProxyBypass + Specifies proxy bypasses. +To replace all existing values with the values you specify, use the following syntax: `"Value1","Value2",..."ValueN"`. + +To add values without affecting existing values, use the following syntax: + +`$a = Get-MpPreference | Select-Object -Expand ProxyBypass` + +`$ += "Value1","Value2"..."ValueN"` + +`Set-MpPreference -ProxyBypass $a` + +To remove values without affecting existing values, do the following steps: + +- Run the following commands to see the existing list of values in order: + + `$x = Get-MpPreference` + + `$r = [System.Collections.ArrayList]($x.ProxyBypass)` + + `$r` + + The first value in the list has the index number 0, the second has the index number 1, and so on. + +- Use the index number to specify the value to remove. For example, to remove the seventh value in +the list, run the following commands: + + `$r.RemoveAt(6)` + + `Set-MpPreference -ProxyBypass $r` + ```yaml Type: String[] Parameter Sets: (All) @@ -1254,6 +1870,7 @@ Accept wildcard characters: False ``` ### -ProxyPacUrl + Specifies the Privilege Attribute Certificate (PAC) proxy. ```yaml @@ -1269,6 +1886,7 @@ Accept wildcard characters: False ``` ### -ProxyServer + Specifies the proxy server. ```yaml @@ -1284,13 +1902,18 @@ Accept wildcard characters: False ``` ### -PUAProtection -Specifies the level of detection for potentially unwanted applications. -When potentially unwanted software is downloaded or attempts to install itself on your computer, you are warned. + +Specifies the level of detection for potentially unwanted applications. Valid values are: + +- 0 or Disabled +- 1 or Enabled: You're warned when potentially unwanted software is downloaded or attempts to install +itself on your computer. +- 2 or Audit ```yaml Type: PUAProtectionType Parameter Sets: (All) -Aliases: +Aliases: Accepted values: Disabled, Enabled, AuditMode Required: False @@ -1301,8 +1924,9 @@ Accept wildcard characters: False ``` ### -QuarantinePurgeItemsAfterDelay -Specifies the number of days to keep items in the Quarantine folder. -If you specify a value of zero or do not specify a value for this parameter, items stay in the Quarantine folder indefinitely. + +Specifies the number of days to keep items in the Quarantine folder. A valid value is an integer +from 0 to 4294967295. The value 0 means items stay in the Quarantine folder indefinitely. ```yaml Type: UInt32 @@ -1317,10 +1941,17 @@ Accept wildcard characters: False ``` ### -RandomizeScheduleTaskTimes -Indicates whether to select a random time for the scheduled start and scheduled update for definitions. -If you specify a value of $True or do not specify a value, scheduled tasks begin within 30 minutes, before or after, the scheduled time. -If you randomize the start times, it can distribute the impact of scanning. -For example, if several virtual machines share the same host, randomized start times prevents all the hosts from starting the scheduled tasks at the same time. + +Specifies whether to select a random time for the scheduled start and scheduled update for +definitions. Valid values are: + +- $true: Scheduled tasks begin within 30 minutes before or after the scheduled time. This is the +default value. +- $false: Scheduled tasks begin on the scheduled time + +Randomized start times can distribute the impact of scanning. For example, if several virtual +machines share the same host, randomized start times prevent all virtual machines from starting the +scheduled tasks at the same time. ```yaml Type: Boolean @@ -1335,17 +1966,18 @@ Accept wildcard characters: False ``` ### -RealTimeScanDirection -Specifies scanning configuration for incoming and outgoing files on NTFS volumes. -The acceptable values for this parameter are: -- 0: Scan both incoming and outgoing files. -This is the default. -- 1: Scan incoming files only. -- 2: Scan outgoing files only. +Specifies scanning configuration for incoming and outgoing files on NTFS volumes. Valid values are: -Specify a value for this parameter to enhance performance on servers which have a large number of file transfers, but need scanning for either incoming or outgoing files. -Evaluate this configuration based on the server role. -For non-NTFS volumes, Windows Defender performs full monitoring of file and program activity. +- 0 or Both: Scan incoming and outgoing files. This is the default value. +- 1 or Incoming: Scan incoming files only. +- 2 or Outcoming \[SP\]: Scan outgoing files only. + +Use this parameter to restrict scanning to incoming or outgoing files on servers that have a large +number of file transfers in only one direction. + +Evaluate this configuration based on the server role. For non-NTFS volumes, Windows Defender +does full monitoring of file and program activity. ```yaml Type: ScanDirection @@ -1361,22 +1993,21 @@ Accept wildcard characters: False ``` ### -RemediationScheduleDay -Specifies the day of the week on which to perform a scheduled full scan in order to complete remediation. -Alternatively, specify everyday for this full scan or never. -The acceptable values for this parameter are: -- 0: Everyday -- 1: Sunday -- 2: Monday -- 3: Tuesday -- 4: Wednesday -- 5: Thursday -- 6: Friday -- 7: Saturday -- 8: Never +Specifies the day of the week to run scheduled full scans to complete remediation. Valid values are: + +- 0 or Everyday +- 1 or Sunday +- 2 or Monday +- 3 or Tuesday +- 4 or Wednesday +- 5 or Thursday +- 6 or Friday +- 7 or Saturday +- 8 or Never (default) -The default value is 8, never. -If you specify a value of 8 or do not specify a value, Windows Defender performs a scheduled full scan to complete remediation by using a default frequency. +For the value 8 or Never, Windows Defender uses a default frequency to run scheduled full scans to +complete remediation. ```yaml Type: Day @@ -1392,9 +2023,13 @@ Accept wildcard characters: False ``` ### -RemediationScheduleTime -Specifies the time of day, as the number of minutes after midnight, to perform a scheduled scan. -The time refers to the local time on the computer. -If you do not specify a value for this parameter, a scheduled scan runs at the default time of two hours after midnight. + +Specifies the time on the local computer to run scheduled scans for remediation. + +To specify a value, enter it as a time span: `hh:mm:ss` where `hh` = hours, `mm` = minutes and `ss` += seconds. For example, `13:30:00` indicates 1:30 PM. + +The default value is `02:00:00` (2:00 AM). ```yaml Type: DateTime @@ -1409,7 +2044,9 @@ Accept wildcard characters: False ``` ### -ReportingAdditionalActionTimeOut -Specifies the number of minutes before a detection in the additional action state changes to the cleared state. + +Specifies the number of minutes before a detection in the additional action state changes to the +cleared state. A valid value is an integer from 0 to 4294967295. ```yaml Type: UInt32 @@ -1424,7 +2061,9 @@ Accept wildcard characters: False ``` ### -ReportingCriticalFailureTimeOut -Specifies the number of minutes before a detection in the critically failed state changes to either the additional action state or the cleared state. + +Specifies the number of minutes before a detection in the critically failed state changes to +the additional action state or the cleared state. A valid value is an integer from 0 to 4294967295. ```yaml Type: UInt32 @@ -1439,7 +2078,9 @@ Accept wildcard characters: False ``` ### -ReportingNonCriticalTimeOut -Specifies the number of minutes before a detection in the non-critically failed state changes to the cleared state. + +Specifies the number of minutes before a detection in the non-critically failed state changes to +the cleared state. A valid value is an integer from 0 to 4294967295. ```yaml Type: UInt32 @@ -1454,12 +2095,21 @@ Accept wildcard characters: False ``` ### -ScanAvgCPULoadFactor + Specifies the maximum percentage CPU usage for a scan. -The acceptable values for this parameter are: integers from 5 through 100, and the value 0, which disables CPU throttling. -Windows Defender does not exceed the percentage of CPU usage that you specify. -The default value is 50. -Note: This is not a hard limit but rather a guidance for the scanning engine to not exceed this maximum on average. If ScanOnlyIfIdleEnabled (instructing the product to scan only when the computer is not in use) and DisableCpuThrottleOnIdleScans (instructing the product to disable CPU throttling on idle scans) are both enabled, then the value of ScanAvgCPULoadFactor is ignored. +A valid value is an integer from 5 to 100. The default value is 50. The value 0 disables CPU +throttling. + +**Note**: This value isn't a hard limit, but rather guidance for the scanning engine to not exceed +the specified value on average. + +The value of this parameter is ignored if both of the following conditions are true: + +- The value of the **ScanOnlyIfIdleEnabled** parameter is $true (scan only when the computer isn't +in use). +- The value of the **DisableCpuThrottleOnIdleScans** parameter is $false (disable CPU throttling on +idle scans). ```yaml Type: Byte @@ -1474,8 +2124,12 @@ Accept wildcard characters: False ``` ### -ScanOnlyIfIdleEnabled -Indicates whether to start scheduled scans only when the computer is not in use. -If you specify a value of $True or do not specify a value, Windows Defender runs schedules scans when the computer is on, but not in use. + +Specifies whether to start scheduled scans only when the computer is not in use. Valid values are: + +- $true: Windows Defender runs schedules scans when the computer is on, but not in use. This is the +default value. +- $false: Windows Defender runs schedules scans when the computer is in use. ```yaml Type: Boolean @@ -1490,18 +2144,16 @@ Accept wildcard characters: False ``` ### -ScanParameters -Specifies the scan type to use during a scheduled scan. -The acceptable values for this parameter are: -- 1: Quick scan -- 2: Full scan +Specifies the scan type to use during a scheduled scan. Valid values are: -If you do not specify this parameter, Windows Defender uses the default value of quick scan. +- 1 or QuickScan (default) +- 2 or FullScan ```yaml Type: ScanType Parameter Sets: (All) -Aliases: +Aliases: Accepted values: QuickScan, FullScan Required: False @@ -1512,10 +2164,12 @@ Accept wildcard characters: False ``` ### -ScanPurgeItemsAfterDelay -Specifies the number of days to keep items in the scan history folder. -After this time, Windows Defender removes the items. -If you specify a value of zero, Windows Defender does not remove items. -If you do not specify a value, Windows Defender removes items from the scan history folder after the default length of time, which is 15 days. + +Specifies the number of days to keep items in the scan history folder. After this time, Windows +Defender removes the items. + +A valid value is an integer from 0 to +4294967295. The default value is 15 days. The value 0 means Windows Defender doesn't remove items from the scan history folder. ```yaml Type: UInt32 @@ -1530,22 +2184,20 @@ Accept wildcard characters: False ``` ### -ScanScheduleDay -Specifies the day of the week on which to perform a scheduled scan. -Alternatively, specify everyday for a scheduled scan or never. -The acceptable values for this parameter are: -- 0: Everyday -- 1: Sunday -- 2: Monday -- 3: Tuesday -- 4: Wednesday -- 5: Thursday -- 6: Friday -- 7: Saturday -- 8: Never +Specifies the day of the week to run scheduled scans. Valid values are: + +- 0 or Everyday +- 1 or Sunday +- 2 or Monday +- 3 or Tuesday +- 4 or Wednesday +- 5 or Thursday +- 6 or Friday +- 7 or Saturday +- 8 or Never (default) -The default value is 8, never. -If you specify a value of 8 or do not specify a value, Windows Defender does not perform scheduled scans. +For the value 8 or Never, Windows Defender doesn't do scheduled scans. ```yaml Type: Day @@ -1560,16 +2212,18 @@ Accept pipeline input: False Accept wildcard characters: False ``` -### -ScanScheduleQuickScanTime -Specifies the time of day, as the number of minutes after midnight, to perform a scheduled quick scan. -The time refers to the local time on the computer. -If you do not specify a value for this parameter, a scheduled quick scan runs at the time specified by the **ScanScheduleOffset** parameter. -That parameter has a default time of two hours after midnight. +### -ScanScheduleOffset + +Specifies the number of minutes after midnight on the local computer to run scheduled scans. The +default value is 120, which means scheduled scans start on the local computer at 2:00 AM. + +If you don't specify a value for this parameter, scheduled scans start at the time specified by the +**ScanScheduleTime** and **ScanScheduleQuickScanTime** parameters. ```yaml -Type: DateTime +Type: UInt32 Parameter Sets: (All) -Aliases: scsqst +Aliases: scso Required: False Position: Named @@ -1578,12 +2232,24 @@ Accept pipeline input: False Accept wildcard characters: False ``` -### -ScanScheduleOffset -Configures the number of minutes after midnight to perform a scheduled scan. The time on the endpoint is used to determine the local time. If you enable this setting, a scheduled scan will run at the time specified. If you disable or don’t enable this setting, a scheduled scan runs at the default time of two hours (120 minutes) after midnight. +### -ScanScheduleQuickScanTime + +Specifies the time on the local computer to run scheduled quick scans. + +To specify a value, enter it as a time span: `hh:mm:ss` where `hh` = hours, `mm` = minutes and `ss` += seconds. For example, `13:30:00` indicates 1:30 PM. + +The default value is `02:00:00` (2:00 AM). + +If you don't specify a value for this parameter, scheduled quick scans run at the time specified +by the **ScanScheduleOffset** parameter. ```yaml -Type: UInt32 -Aliases: scso +Type: DateTime +Parameter Sets: (All) +Aliases: scsqst + +Required: False Position: Named Default value: None Accept pipeline input: False @@ -1591,11 +2257,20 @@ Accept wildcard characters: False ``` ### -ScanScheduleTime -Specifies the time of day to run a scheduled scan. The time refers to the local time on the computer. Specify the number of minutes after midnight (for example, enter 60 for 1 a.m.). This parameter has a default time of two hours after midnight (2 a.m.). + +Specifies the time on the local computer to run scheduled scans. + +To specify a value, enter it as a time span: `hh:mm:ss` where `hh` = hours, `mm` = minutes and `ss` += seconds. For example, `13:30:00` indicates 1:30 PM. + +The default value is `02:00:00` (2:00 AM). + +If you don't specify a value for this parameter, scheduled scans run at the time specified +by the **ScanScheduleOffset** parameter. ```yaml Type: DateTime -Aliases: scsqst +Aliases: scst Position: Named Default value: None Accept pipeline input: False @@ -1603,7 +2278,9 @@ Accept wildcard characters: False ``` ### -SchedulerRandomizationTime -Specifies the randomization time for the scheduler. + +Specifies the randomization time for the scheduler. A valid value is an integer from 0 to +4294967295. ```yaml Type: UInt32 @@ -1618,11 +2295,17 @@ Accept wildcard characters: False ``` ### -ServiceHealthReportInterval -This policy setting configures the time interval (in minutes) for the service health reports to be sent from endpoints. These are for Microsoft Defender Antivirus events 1150 and 1151. For more information, see [Microsoft Defender Antivirus event IDs](/microsoft-365/security/defender-endpoint/troubleshoot-microsoft-defender-antivirus#microsoft-defender-antivirus-event-ids). -If you do not configure this setting, the default value will be applied. The default value is set at 60 minutes (one hour). -If you configure this setting to 0, no service health reports will be sent. -The maximum value allowed to be set is 14400 minutes (ten days). + + +Specifies the time interval in minutes for the service health reports to be sent from endpoints. +These reports are for Microsoft Defender Antivirus events 1150 and 1151. + +A valid value is an integer from 0 to 4294967295. The default value is 60 minutes. The value 0 +means no service health reports are sent. + +For more information, see +[Microsoft Defender Antivirus event IDs](/microsoft-365/security/defender-endpoint/troubleshoot-microsoft-defender-antivirus#microsoft-defender-antivirus-event-ids). ```yaml Type: UInt32 @@ -1635,12 +2318,19 @@ Accept wildcard characters: False ``` ### -SevereThreatDefaultAction -Specifies which automatic remediation action to take for a severe level threat. -The acceptable values for this parameter are: -- Quarantine -- Remove -- Ignore + + +Specifies which automatic remediation action to take for severe level threats. Valid values are: + +- Clean +- Quarantine +- Remove +- Allow +- UserDefined +- NoAction +- Block ```yaml Type: ThreatAction @@ -1656,7 +2346,11 @@ Accept wildcard characters: False ``` ### -SharedSignaturesPath -Specifies the shared signatures path. + +Specifies the shared signatures path. For example, `"P:\Signature Data"`. If the value contains +spaces, enclose the value in quotation marks ("). + +To empty this setting, use the value `" "`. ```yaml Type: String @@ -1671,8 +2365,17 @@ Accept wildcard characters: False ``` ### -SignatureAuGracePeriod -Specifies a grace period, in minutes, for the definition. -If a definition successfully updates within this period, Windows Defender abandons any service initiated updates. + +Specified the grace period in minutes that's applied to all signature updates after the initial, +first-time application. + +A valid value is an integer from 0 to 4294967295. + +If Windows Defender successfully updates within this period, any service initiated updates are +abandoned. + +THe **SignatureFirstAuGracePeriod** parameter specifies the grace period when a new signature is +first detected. ```yaml Type: UInt32 @@ -1687,7 +2390,12 @@ Accept wildcard characters: False ``` ### -SignatureBlobFileSharesSources -Specifies the file shares sources for signatures. + +Specifies the file shares sources for signatures. For example, +`"\\ServerName\\ShareName\Folder name\"`. If the value contains spaces, enclose the value in +quotation marks ("). + +To empty this setting, use the value `" "`. ```yaml Type: String @@ -1702,7 +2410,8 @@ Accept wildcard characters: False ``` ### -SignatureBlobUpdateInterval -Specifies the signature update interval. + +Specifies the signature update interval. A valid value is an integer from 0 to 4294967295. ```yaml Type: UInt32 @@ -1717,11 +2426,17 @@ Accept wildcard characters: False ``` ### -SignatureDefinitionUpdateFileSharesSources + Specifies file-share sources for definition updates. -Specify sources as a bracketed sequence of Universal Naming Convention (UNC) locations, separated by the pipeline symbol; for example, { \\\\Server01\Share01 | \\\\Server02\Share02 | \\\\Server03\Share03}. -If you specify a value for this parameter, Windows Defender attempts to connect to the shares in the order that you specify. -After Windows Defender updates a definition, it stops attempting to connect to shares on the list. -If you do not specify a value for this parameter, the list is empty. + +A valid value uses the following syntax: +`{\\Server1\Share1 | \\Server2\Share2 | ... \\ServerN\ShareN}`. + +Windows Defender tries to connect to the shared folders in the specified order. After the update +is successful, Windows Defender stops trying to connect to the remaining shared folders in the +list. + +To empty this setting, use the value `" "`. ```yaml Type: String @@ -1736,9 +2451,12 @@ Accept wildcard characters: False ``` ### -SignatureDisableUpdateOnStartupWithoutEngine -Indicates whether to initiate definition updates even if no antimalware engine is present. -If you specify a value of $True or do not specify a value, Windows Defender does not initiate definition updates on startup. -If you specify a value of $False, and if no antimalware engine is present, Windows Defender initiates definition updates on startup. + +Specifies whether to initiate definition updates even if no antimalware engine is present. Valid values are: + +- $true: Windows Defender does not initiate definition updates on startup. This is the default value +- $false: If no antimalware engine is present, Windows Defender initiates definition updates on +startup. ```yaml Type: Boolean @@ -1753,20 +2471,20 @@ Accept wildcard characters: False ``` ### -SignatureFallbackOrder -Specifies the order in which to contact different definition update sources. -Specify the types of update sources in the order in which you want Windows Defender to contact them, enclosed in braces and separated by the pipeline symbol; for example, { InternalDefinitionUpdateServer | MicrosoftUpdateServer | MMPC }. -The values that you can specify in the string are: + +Specifies the order in which to contact different definition update sources. The available sources +are: - InternalDefinitionUpdateServer - MicrosoftUpdateServer -- MMPC -- FileShares +- MMPC (Microsoft Malware Protection Center) +- FileShares (specified by the **SignatureDefinitionUpdateFileSharesSources** parameter) -MMPC refers to Microsoft Malware Protection Center. +A valid value uses the following syntax: `{Source1 | Source2 | Source3 |Source4}`. The default +value is `{MicrosoftUpdateServer | MMPC}`. -If you specify a value for this parameter, Windows Defender contacts the definition update sources in the specified order. -After Windows Defender downloads definition updates from a source, it stops attempting to connect to other sources. -If you do not specify a value for this parameter, Windows Defender contacts sources in the default order of { MicrosoftUpdateServer | MMPC }. +Windows Defender tries to connect to the sources in the specified order. After the update +is successful, Windows Defender stops trying to connect to the remaining sources in the list. ```yaml Type: String @@ -1781,10 +2499,21 @@ Accept wildcard characters: False ``` ### -SignatureFirstAuGracePeriod -Specifies a grace period, in minutes, for the definition. -If a definition successfully updates within this period, Windows Defender abandons any service initiated updates. + +Specifies the grace period in minutes that's given to a new signature when it's first applied. This +grace period allows more time for compatibility checks with new detection logic. For example, to +prevent false positives from triggering alerts. + +A valid value is an integer from 20 to 4320. + +If Windows Defender successfully updates within this period, any service initiated updates are +abandoned. + This parameter overrides the value of the **CheckForSignaturesBeforeRunningScan** parameter. +The **SignatureAuGracePeriod** parameter specifies the standard grace period for all subsequent +signature updates. + ```yaml Type: UInt32 Parameter Sets: (All) @@ -1798,22 +2527,20 @@ Accept wildcard characters: False ``` ### -SignatureScheduleDay -Specifies the day of the week on which to check for definition updates. -Alternatively, specify everyday for a scheduled scan or never. -The acceptable values for this parameter are: -- 0: Everyday -- 1: Sunday -- 2: Monday -- 3: Tuesday -- 4: Wednesday -- 5: Thursday -- 6: Friday -- 7: Saturday -- 8: Never +Specifies the day of the week on which to check for definition updates. Valid values are: -The default value is 8, never. -If you specify a value of 8 or do not specify a value, Windows Defender checks for definition updates by using a default frequency. +- 0 or Everyday +- 1 or Sunday +- 2 or Monday +- 3 or Tuesday +- 4 or Wednesday +- 5 or Thursday +- 6 or Friday +- 7 or Saturday +- 8 or Never (default) + +For the value 8 or Never, Windows Defender uses a default frequency to check for definition updates. ```yaml Type: Day @@ -1829,37 +2556,19 @@ Accept wildcard characters: False ``` ### -SignatureScheduleTime -Specifies the time of day, as the number of minutes after midnight, to check for definition updates. -The time refers to the local time on the computer. -If you do not specify a value for this parameter, Windows Defender checks for definition updates at the default time of 15 minutes before the scheduled scan time. - -```yaml -Type: DateTime -Parameter Sets: (All) -Aliases: sigst - -Required: False -Position: Named -Default value: None -Accept pipeline input: False -Accept wildcard characters: False -``` - -### -SignaturesUpdatesChannel -Specifies when devices receive daily Microsoft Defender definition updates during the monthly gradual rollout. -Valid values are: +Specifies the time on the local computer to check for definition updates. -- NotConfigured. Devices stay up to date automatically during the gradual release cycle. This value is suitable for most devices. -- Broad. Devices are offered updates only after the gradual release cycle completes. This value is suggested for a broad set of devices in your production population, from 10 to 100 percent. -- Staged. Devices are offered updates after the monthly gradual release cycle. This value is suggested for a small, representative part of your production population, around 10 percent. +To specify a value, enter it as a time span: `hh:mm:ss` where `hh` = hours, `mm` = minutes and `ss` += seconds. For example, `13:30:00` indicates 1:30 PM. -This parameter name will be updated to **DefinitionUpdatesChannel** in a future release. +If you don't specify a value for this parameter, Windows Defender checks for definition updates 15 +minutes before the scheduled scan time by default. ```yaml -Type: UpdatesChannelType +Type: DateTime Parameter Sets: (All) -Aliases: srelr +Aliases: sigst Required: False Position: Named @@ -1869,8 +2578,10 @@ Accept wildcard characters: False ``` ### -SignatureUpdateCatchupInterval + Specifies the number of days after which Windows Defender requires a catch-up definition update. -If you do not specify a value for this parameter, Windows Defender requires a catch-up definition update after the default value of one day. + +A valid value is an integer from 0 to 4294967295. The default value is one day. ```yaml Type: UInt32 @@ -1885,10 +2596,15 @@ Accept wildcard characters: False ``` ### -SignatureUpdateInterval -Specifies the interval, in hours, at which to check for definition updates. -The acceptable values for this parameter are: integers from 1 through 24. -If you do not specify a value for this parameter, Windows Defender checks at the default interval. -You can use this parameter instead of the **SignatureScheduleDay** parameter and **SignatureScheduleTime** parameter. + + + +Specifies the interval in hours to check for definition updates. + +A valid value is an integer from 0 to 4294967295. + +You can use this parameter instead of the **SignatureScheduleDay**and **SignatureScheduleTime** +parameters. ```yaml Type: UInt32 @@ -1903,20 +2619,21 @@ Accept wildcard characters: False ``` ### -SubmitSamplesConsent -Specifies how Windows Defender checks for user consent for certain samples. -If consent has previously been granted, Windows Defender submits the samples. -Otherwise, if the **MAPSReporting** parameter does not have a value of Disabled, Windows Defender prompts the user for consent. -The acceptable values for this parameter are: -- 0: Always prompt -- 1: Send safe samples automatically -- 2: Never send -- 3: Send all samples automatically +Specifies how Windows Defender checks for user consent for certain samples. Valid values are: + +- 0 or AlwaysPrompt +- 1 or SendSafeSamples +- 2 or NeverSend +- 3 or SendAllSamples + +If consent was previously granted, Windows Defender submits the samples. Otherwise, Windows Defender +prompts the user for consent if the value of the **MAPSReporting** parameter isn't Disabled. ```yaml Type: SubmitSamplesConsentType Parameter Sets: (All) -Aliases: +Aliases: Accepted values: AlwaysPrompt, SendSafeSamples, NeverSend, SendAllSamples Required: False @@ -1927,19 +2644,46 @@ Accept wildcard characters: False ``` ### -ThreatIDDefaultAction_Actions -Specifies an array of the actions to take for the IDs specified by using the **ThreatIDDefaultAction_Ids** parameter. -The acceptable values for this parameter are: -- 1: Clean -- 2: Quarantine -- 3: Remove -- 6: Allow -- 8: UserDefined -- 9: NoAction -- 10: Block +Use the **ThreatIDDefaultAction_Ids** and **ThreatIDDefaultAction_Actions** parameters +together in the same command to specify the actions to take on the corresponding threats. + +- The **ThreatIDDefaultAction_Ids** parameter identifies the threat from the output of the +**Get-MpThreatCatalog** cmdlet. For example, the ThreatID value of the threat named +**Trojan:Win32/BlueFire** is `3229`. +- The **ThreatIDDefaultAction_Actions** parameter identifies the action to take on the corresponding +threat ID. Valid values are: + + • 1 or Clean ->[!NOTE] ->A value of 0 (NULL) applies an action based on the Security Intelligence Update (SIU). This is the default value. + • 2 or Quarantine + + • 3 or Remove + + • 6 or Allow + + • 8 or UserDefined + + • 9 or NoAction + + • 10 or Block + +To replace all existing values with the values you specify, use the following syntax: + +`Set-MpPreference -ThreatIDDefaultAction_Ids ThreatID1,ThreatID2,...ThreatIDN -ThreatIDDefaultAction_Actions Action1,Action2,...ActionN` + +To add values without affecting existing values, use the **Add-MPPreference** cmdlet: + +`Add-MpPreference -ThreatIDDefaultAction_Ids ThreatID1,ThreatID2,...ThreatIDN -ThreatIDDefaultAction_Actions Action1,Action2,...ActionN` + +To remove values without affecting other existing values, use the **Remove-MPPreference** cmdlet: + +`Remove-MpPreference -ThreatIDDefaultAction_Ids ThreatID1,ThreatID2,...ThreatIDN -ThreatIDDefaultAction_Actions Action1,Action2,...ActionN` + +**Note**: When a threat and corresponding action aren't specified in the +**ThreatIDDefaultAction_Ids** and **ThreatIDDefaultAction_Actions** parameters, the action that's +applied to the threat is based on the Security Intelligence Update (SIU). By default, no threats or +corresponding actions are specified in the parameters. ```yaml Type: ThreatAction[] @@ -1955,8 +2699,46 @@ Accept wildcard characters: False ``` ### -ThreatIDDefaultAction_Ids -Specifies an array of threat IDs. -This cmdlet modifies the default action for the threat IDs that you specify. + +Use the **ThreatIDDefaultAction_Ids** and **ThreatIDDefaultAction_Actions** parameters +together in the same command to specify the actions to take on the corresponding threats. + +- The **ThreatIDDefaultAction_Ids** parameter identifies the threat from the output of the +**Get-MpThreatCatalog** cmdlet. For example, the ThreatID value of the threat named +**Trojan:Win32/BlueFire** is `3229`. +- The **ThreatIDDefaultAction_Actions** parameter identifies the action to take on the corresponding +threat ID. Valid values are: + + • 1 or Clean + + • 2 or Quarantine + + • 3 or Remove + + • 6 or Allow + + • 8 or UserDefined + + • 9 or NoAction + + • 10 or Block + +To replace all existing values with the values you specify, use the following syntax: + +`Set-MpPreference -ThreatIDDefaultAction_Ids ThreatID1,ThreatID2,...ThreatIDN -ThreatIDDefaultAction_Actions Action1,Action2,...ActionN` + +To add values without affecting existing values, use the **Add-MPPreference** cmdlet: + +`Add-MpPreference -ThreatIDDefaultAction_Ids ThreatID1,ThreatID2,...ThreatIDN -ThreatIDDefaultAction_Actions Action1,Action2,...ActionN` + +To remove values without affecting other existing values, use the **Remove-MPPreference** cmdlet: + +`Remove-MpPreference -ThreatIDDefaultAction_Ids ThreatID1,ThreatID2,...ThreatIDN -ThreatIDDefaultAction_Actions Action1,Action2,...ActionN` + +**Note**: When a threat and corresponding action aren't specified in the +**ThreatIDDefaultAction_Ids** and **ThreatIDDefaultAction_Actions** parameters, the action that's +applied to the threat is based on the Security Intelligence Update (SIU). By default, no threats or +corresponding actions are specified in the parameters. ```yaml Type: Int64[] @@ -1971,14 +2753,19 @@ Accept wildcard characters: False ``` ### -ThrottleLimit -Specifies the maximum number of concurrent operations that can be established to run the cmdlet. -If this parameter is omitted or a value of `0` is entered, then Windows PowerShell® calculates an optimum throttle limit for the cmdlet based on the number of CIM cmdlets that are running on the computer. + +Specifies the maximum number of concurrent operations that can be established to run this cmdlet. + +A valid value is an integer from 0 to 2147483647. The default value is 0, which means PowerShell +calculates an optimum throttle limit for the cmdlet based on the number of CIM cmdlets that are +running on the computer. + The throttle limit applies only to the current cmdlet, not to the session or to the computer. ```yaml Type: Int32 Parameter Sets: (All) -Aliases: +Aliases: Required: False Position: Named @@ -1988,15 +2775,16 @@ Accept wildcard characters: False ``` ### -ThrottleForScheduledScanOnly -A CPU usage limit can be applied to scheduled scans only, or to scheduled and custom scans. The default value applies a CPU usage limit to scheduled scans only. -The acceptable values for this parameter are: -- 1 (Default) - If you enable this setting, CPU throttling will apply only to scheduled scans. -- 0 - If you disable this setting, CPU throttling will apply to scheduled and custom scans. + +Specifies whether a CPU usage limit applies scheduled scans only. Valid values are: + +- $true: CPU throttling applies only to scheduled scans. This is the default value. +- $false: CPU throttling applies to scheduled and custom scans. ```yaml Type: Boolean Parameter Sets: (All) -Aliases: +Aliases: Required: False Position: Named @@ -2005,16 +2793,17 @@ Accept pipeline input: False Accept wildcard characters: False ``` - ### -UILockdown -Indicates whether to disable UI lockdown mode. -If you specify a value of $True, Windows Defender disables UI lockdown mode. -If you specify $False or do not specify a value, UI lockdown mode is enabled. + +Specifies whether to disable UI lockdown mode. Valid values are: + +- $true: UI lockdown mode is disabled. +- $false: UI lockdown mode is enabled ```yaml Type: Boolean Parameter Sets: (All) -Aliases: +Aliases: Required: False Position: Named @@ -2024,12 +2813,19 @@ Accept wildcard characters: False ``` ### -UnknownThreatDefaultAction -Specifies which automatic remediation action to take for an unknown level threat. -The acceptable values for this parameter are: -- Quarantine -- Remove -- Ignore + + +Specifies the automatic remediation action to take for unknown level threats. Valid values are: + +- 1 or Clean +- 2 or Quarantine +- 3 or Remove +- 6 or Allow +- 8 or UserDefined +- 9 or NoAction +- 10 or Block ```yaml Type: ThreatAction @@ -2060,4 +2856,3 @@ This cmdlet supports the common parameters: -Debug, -ErrorAction, -ErrorVariable [Get-MpPreference](./Get-MpPreference.md) [Remove-MpPreference](./Remove-MpPreference.md) - diff --git a/docset/winserver2022-ps/defender/Start-MpScan.md b/docset/winserver2022-ps/defender/Start-MpScan.md index 6048dd4b75..292b42d5f2 100644 --- a/docset/winserver2022-ps/defender/Start-MpScan.md +++ b/docset/winserver2022-ps/defender/Start-MpScan.md @@ -16,8 +16,13 @@ Starts a scan on a computer. ## SYNTAX ``` -Start-MpScan [-ScanPath ] [-ScanType ] [-CimSession ] [-ThrottleLimit ] - [-AsJob] [] +Start-MpScan + [-AsJob] + [-CimSession ] + [-ScanPath ] + [-ScanType ] + [-ThrottleLimit ] + [] ``` ## DESCRIPTION @@ -27,7 +32,7 @@ The cmdlet performs scans for the path you specify. ## EXAMPLES ### Example 1: Start a scan -``` +```powershell PS C:\> Start-MpScan ``` @@ -36,19 +41,19 @@ This command starts a scan on the computer on which you run the cmdlet. ## PARAMETERS ### -AsJob -Runs the cmdlet as a background job. Use this parameter to run commands that take a long time to complete. +Runs the cmdlet as a background job. Use this parameter to run commands that take a long time to complete. -The cmdlet immediately returns an object that represents the job and then displays the command prompt. -You can continue to work in the session while the job completes. -To manage the job, use the `*-Job` cmdlets. -To get the job results, use the [Receive-Job](https://go.microsoft.com/fwlink/?LinkID=113372) cmdlet. +The cmdlet immediately returns an object that represents the job and then displays the command prompt. +You can continue to work in the session while the job completes. +To manage the job, use the `*-Job` cmdlets. +To get the job results, use the [Receive-Job](https://go.microsoft.com/fwlink/?LinkID=113372) cmdlet. For more information about Windows PowerShell background jobs, see [about_Jobs](https://go.microsoft.com/fwlink/?LinkID=113251). ```yaml Type: SwitchParameter Parameter Sets: (All) -Aliases: +Aliases: Required: False Position: Named @@ -58,8 +63,8 @@ Accept wildcard characters: False ``` ### -CimSession -Runs the cmdlet in a remote session or on a remote computer. -Enter a computer name or a session object, such as the output of a [New-CimSession](https://go.microsoft.com/fwlink/p/?LinkId=227967) or [Get-CimSession](https://go.microsoft.com/fwlink/p/?LinkId=227966) cmdlet. +Runs the cmdlet in a remote session or on a remote computer. +Enter a computer name or a session object, such as the output of a [New-CimSession](https://go.microsoft.com/fwlink/p/?LinkId=227967) or [Get-CimSession](https://go.microsoft.com/fwlink/p/?LinkId=227966) cmdlet. The default is the current session on the local computer. ```yaml @@ -81,7 +86,7 @@ Specify a file name, a folder name, such as C:\, or a UNC path. ```yaml Type: String Parameter Sets: (All) -Aliases: +Aliases: Required: False Position: Named @@ -101,7 +106,7 @@ The acceptable values for this parameter are: ```yaml Type: ScanType Parameter Sets: (All) -Aliases: +Aliases: Accepted values: FullScan, QuickScan, CustomScan Required: False @@ -119,7 +124,7 @@ The throttle limit applies only to the current cmdlet, not to the session or to ```yaml Type: Int32 Parameter Sets: (All) -Aliases: +Aliases: Required: False Position: Named @@ -138,4 +143,3 @@ This cmdlet supports the common parameters: -Debug, -ErrorAction, -ErrorVariable ## NOTES ## RELATED LINKS - diff --git a/docset/winserver2022-ps/defender/Start-MpWDOScan.md b/docset/winserver2022-ps/defender/Start-MpWDOScan.md index 372430fc11..f5188befb3 100644 --- a/docset/winserver2022-ps/defender/Start-MpWDOScan.md +++ b/docset/winserver2022-ps/defender/Start-MpWDOScan.md @@ -16,7 +16,11 @@ Starts a Windows Defender offline scan. ## SYNTAX ``` -Start-MpWDOScan [-CimSession ] [-ThrottleLimit ] [-AsJob] [] +Start-MpWDOScan + [-AsJob] + [-CimSession ] + [-ThrottleLimit ] + [] ``` ## DESCRIPTION @@ -25,7 +29,7 @@ The **Start-MpWDOScan** cmdlet starts a Windows Defender offline scan on a compu ## EXAMPLES ### Example 1: Start an offline scan -``` +```powershell PS C:\>Start-MpWDOScan ``` @@ -35,19 +39,19 @@ This command causes the computer to start in Windows Defender offline and begin ## PARAMETERS ### -AsJob -Runs the cmdlet as a background job. Use this parameter to run commands that take a long time to complete. +Runs the cmdlet as a background job. Use this parameter to run commands that take a long time to complete. -The cmdlet immediately returns an object that represents the job and then displays the command prompt. -You can continue to work in the session while the job completes. -To manage the job, use the `*-Job` cmdlets. -To get the job results, use the [Receive-Job](https://go.microsoft.com/fwlink/?LinkID=113372) cmdlet. +The cmdlet immediately returns an object that represents the job and then displays the command prompt. +You can continue to work in the session while the job completes. +To manage the job, use the `*-Job` cmdlets. +To get the job results, use the [Receive-Job](https://go.microsoft.com/fwlink/?LinkID=113372) cmdlet. For more information about Windows PowerShell background jobs, see [about_Jobs](https://go.microsoft.com/fwlink/?LinkID=113251). ```yaml Type: SwitchParameter Parameter Sets: (All) -Aliases: +Aliases: Required: False Position: Named @@ -57,8 +61,8 @@ Accept wildcard characters: False ``` ### -CimSession -Runs the cmdlet in a remote session or on a remote computer. -Enter a computer name or a session object, such as the output of a [New-CimSession](https://go.microsoft.com/fwlink/p/?LinkId=227967) or [Get-CimSession](https://go.microsoft.com/fwlink/p/?LinkId=227966) cmdlet. +Runs the cmdlet in a remote session or on a remote computer. +Enter a computer name or a session object, such as the output of a [New-CimSession](https://go.microsoft.com/fwlink/p/?LinkId=227967) or [Get-CimSession](https://go.microsoft.com/fwlink/p/?LinkId=227966) cmdlet. The default is the current session on the local computer. ```yaml @@ -81,7 +85,7 @@ The throttle limit applies only to the current cmdlet, not to the session or to ```yaml Type: Int32 Parameter Sets: (All) -Aliases: +Aliases: Required: False Position: Named @@ -100,4 +104,3 @@ This cmdlet supports the common parameters: -Debug, -ErrorAction, -ErrorVariable ## NOTES ## RELATED LINKS - diff --git a/docset/winserver2022-ps/defender/Update-MpSignature.md b/docset/winserver2022-ps/defender/Update-MpSignature.md index cb0efc1767..af9ed08a17 100644 --- a/docset/winserver2022-ps/defender/Update-MpSignature.md +++ b/docset/winserver2022-ps/defender/Update-MpSignature.md @@ -16,8 +16,12 @@ Updates the antimalware definitions on a computer. ## SYNTAX ``` -Update-MpSignature [-UpdateSource ] [-CimSession ] [-ThrottleLimit ] - [-AsJob] [] +Update-MpSignature + [-AsJob] + [-CimSession ] + [-ThrottleLimit ] + [-UpdateSource ] + [] ``` ## DESCRIPTION @@ -26,7 +30,7 @@ The **Update-MpSignature** cmdlet updates the antimalware definitions with the l ## EXAMPLES ### Example 1: Update signatures -``` +```powershell PS C:\> Update-MpSignature ``` @@ -34,7 +38,7 @@ This command updates the antimalware definitions. By default, the cmdlet uses the sources configured through [SignatureFallbackOrder](Set-MpPreference.yml#-signaturefallbackorder). If no signature fallback order is configured, the cmdlet uses the default update source. ### Example 2: Update signatures from a specific source -``` +```powershell PS C:\> Update-MpSignature -UpdateSource MicrosoftUpdateServer ``` @@ -43,19 +47,19 @@ This command updates the antimalware definitions from the Microsoft Update Serve ## PARAMETERS ### -AsJob -Runs the cmdlet as a background job. Use this parameter to run commands that take a long time to complete. +Runs the cmdlet as a background job. Use this parameter to run commands that take a long time to complete. -The cmdlet immediately returns an object that represents the job and then displays the command prompt. -You can continue to work in the session while the job completes. -To manage the job, use the `*-Job` cmdlets. -To get the job results, use the [Receive-Job](https://go.microsoft.com/fwlink/?LinkID=113372) cmdlet. +The cmdlet immediately returns an object that represents the job and then displays the command prompt. +You can continue to work in the session while the job completes. +To manage the job, use the `*-Job` cmdlets. +To get the job results, use the [Receive-Job](https://go.microsoft.com/fwlink/?LinkID=113372) cmdlet. For more information about Windows PowerShell background jobs, see [about_Jobs](https://go.microsoft.com/fwlink/?LinkID=113251). ```yaml Type: SwitchParameter Parameter Sets: (All) -Aliases: +Aliases: Required: False Position: Named @@ -65,8 +69,8 @@ Accept wildcard characters: False ``` ### -CimSession -Runs the cmdlet in a remote session or on a remote computer. -Enter a computer name or a session object, such as the output of a [New-CimSession](https://go.microsoft.com/fwlink/p/?LinkId=227967) or [Get-CimSession](https://go.microsoft.com/fwlink/p/?LinkId=227966) cmdlet. +Runs the cmdlet in a remote session or on a remote computer. +Enter a computer name or a session object, such as the output of a [New-CimSession](https://go.microsoft.com/fwlink/p/?LinkId=227967) or [Get-CimSession](https://go.microsoft.com/fwlink/p/?LinkId=227966) cmdlet. The default is the current session on the local computer. ```yaml @@ -89,7 +93,7 @@ The throttle limit applies only to the current cmdlet, not to the session or to ```yaml Type: Int32 Parameter Sets: (All) -Aliases: +Aliases: Required: False Position: Named @@ -106,7 +110,7 @@ The acceptable values for this parameter are: - InternalDefinitionUpdateServer - MicrosoftUpdateServer -- MMPC +- MMPC - FileShares If you specify the InternalDefinitionUpdateServer setting, the service checks for updates on the Windows Software Update Services (WSUS) server. @@ -114,7 +118,7 @@ If you specify the InternalDefinitionUpdateServer setting, the service checks fo ```yaml Type: UpdateSource Parameter Sets: (All) -Aliases: +Aliases: Accepted values: InternalDefinitionUpdateServer, MicrosoftUpdateServer, MMPC, FileShares Required: False @@ -134,5 +138,3 @@ This cmdlet supports the common parameters: -Debug, -ErrorAction, -ErrorVariable ## NOTES ## RELATED LINKS - - diff --git a/docset/winserver2022-ps/dism/Add-WindowsPackage.md b/docset/winserver2022-ps/dism/Add-WindowsPackage.md index 1f6e1dd32b..ce8bfaf4b0 100644 --- a/docset/winserver2022-ps/dism/Add-WindowsPackage.md +++ b/docset/winserver2022-ps/dism/Add-WindowsPackage.md @@ -275,6 +275,10 @@ This cmdlet supports the common parameters: -Debug, -ErrorAction, -ErrorVariable ## NOTES +**Checkpoint cumulative updates** + +Starting with Windows 11, version 24H2, the latest cumulative update may have a prerequisite cumulative update that is required to be installed first. To install these checkpoint cumulative updates, call Add-WindowsPackage with the target cumulative update. The folder from -PackagePath will be used to discover and install one or more checkpoints as needed. Only the target cumulative update and any prerequisite checkpoint cumulative updates should be in the -PackagePath folder. Cumulative update packages with a revision less than or equal to the target cumulative update will be processed. + ## RELATED LINKS [Get-WindowsPackage](./Get-WindowsPackage.md) diff --git a/docset/winserver2022-ps/dism/Get-WindowsReservedStorageState.md b/docset/winserver2022-ps/dism/Get-WindowsReservedStorageState.md index ed7c3ff534..586d6c1108 100644 --- a/docset/winserver2022-ps/dism/Get-WindowsReservedStorageState.md +++ b/docset/winserver2022-ps/dism/Get-WindowsReservedStorageState.md @@ -18,13 +18,13 @@ Get-WindowsReservedStorageState [-LogPath ] [-ScratchDirectory ] ``` ## DESCRIPTION -Gets the current state of reserved storage. This command is supported with the online Windows image. +Gets the current state of reserved storage. This command is only supported with the online Windows image. ## EXAMPLES ### Example 1 ```powershell -PS C:\> Get-WindowsReservedStorageState -Online +PS C:\> Get-WindowsReservedStorageState ``` This command gets the Windows reserved storage state on the local host. diff --git a/docset/winserver2022-ps/hyper-v/Add-VMAssignableDevice.md b/docset/winserver2022-ps/hyper-v/Add-VMAssignableDevice.md new file mode 100644 index 0000000000..fbd55101fc --- /dev/null +++ b/docset/winserver2022-ps/hyper-v/Add-VMAssignableDevice.md @@ -0,0 +1,275 @@ +--- +description: Assigns a device to a virtual machine. +external help file: Microsoft.HyperV.PowerShell.Cmdlets.dll-Help.xml +Module Name: Hyper-V +ms.date: 06/12/2024 +online version: https://learn.microsoft.com/powershell/module/hyper-v/add-vmassignabledevice?view=windowsserver2022-ps&wt.mc_id=ps-gethelp +schema: 2.0.0 +title: Add-VMAssignableDevice +--- + +# Add-VMAssignableDevice + +## SYNOPSIS +Adds an assignable device to a specific virtual machine. + +## SYNTAX + +### VMName (Default) + +``` +Add-VMAssignableDevice [-CimSession ] [-ComputerName ] + [-Credential ] [-VMName] [-InstancePath ] + [-LocationPath ] [-VirtualFunction ] [-ResourcePoolName ] [-Passthru] + [-WhatIf] [-Confirm] [] +``` + +### VMObject + +``` +Add-VMAssignableDevice [-VM] [-InstancePath ] [-LocationPath ] + [-VirtualFunction ] [-ResourcePoolName ] [-Passthru] [-WhatIf] [-Confirm] + [] +``` + +## DESCRIPTION + +The `Add-VMAssignableDevice` cmdlet assigns a physical device to a specified virtual machine (VM). +This is commonly used for tasks such as attaching GPUs or network adapters directly to a VM to +enhance performance for specific applications or workloads. The device can be specified through its +instance path, location path, or assignable device object. + +## EXAMPLES + +### Example 1 + +```powershell +Add-VMAssignableDevice -VMName "MyVM" -InstancePath "PCIROOT(0)#PCI(0300)#PCI(0000)" +``` + +This example attaches a physical device, identified by its instance path, to the virtual machine +named **MyVM**. + +## PARAMETERS + +### -CimSession + +Runs the cmdlet in a remote session or on a remote computer. Enter a computer name or a session +object, such as the output of a [New-CimSession](/powershell/module/cimcmdlets/new-cimsession) +or [Get-CimSession](/powershell/module/cimcmdlets/get-cimsession) cmdlet. The default is the +current session on the local computer. + +```yaml +Type: CimSession[] +Parameter Sets: VMName +Aliases: + +Required: False +Position: Named +Default value: None +Accept pipeline input: False +Accept wildcard characters: False +``` + +### -ComputerName + +Specifies one or more Hyper-V hosts on which the assignable devices are to be retrieved. NetBIOS +names, IP addresses, and fully qualified domain names are allowed. The default is the local +computer. Use localhost or a dot (`.`) to specify the local computer explicitly. + +```yaml +Type: String[] +Parameter Sets: VMName +Aliases: + +Required: False +Position: Named +Default value: None +Accept pipeline input: False +Accept wildcard characters: False +``` + +### -Credential + +Specifies one or more user accounts that have permission to perform this action. The default is the +current user. + +```yaml +Type: PSCredential[] +Parameter Sets: VMName +Aliases: + +Required: False +Position: Named +Default value: None +Accept pipeline input: False +Accept wildcard characters: False +``` + +### -InstancePath + +Represents the Device Instance path in the host machine. + +```yaml +Type: String +Parameter Sets: (All) +Aliases: + +Required: False +Position: Named +Default value: None +Accept pipeline input: False +Accept wildcard characters: False +``` + +### -LocationPath + +Specifies the location path to the assignable device + +```yaml +Type: String +Parameter Sets: (All) +Aliases: + +Required: False +Position: Named +Default value: None +Accept pipeline input: False +Accept wildcard characters: False +``` + +### -Passthru + +Returns an object for each process that the cmdlet started. + +```yaml +Type: SwitchParameter +Parameter Sets: (All) +Aliases: + +Required: False +Position: Named +Default value: None +Accept pipeline input: False +Accept wildcard characters: False +``` + +### -ResourcePoolName + +Specifies the name of the resource pool to which the device is to be assigned. + +```yaml +Type: String +Parameter Sets: (All) +Aliases: + +Required: False +Position: Named +Default value: None +Accept pipeline input: False +Accept wildcard characters: False +``` + +### -VirtualFunction + +Specifies the number of the virtual function (VF) of an SR-IOV-capable network adapter assigned to +the virtual machine. + +```yaml +Type: UInt16 +Parameter Sets: (All) +Aliases: + +Required: False +Position: Named +Default value: None +Accept pipeline input: False +Accept wildcard characters: False +``` + +### -VM + +Specifies the virtual machine to which the device is to be assigned. + +```yaml +Type: VirtualMachine[] +Parameter Sets: VMObject +Aliases: + +Required: True +Position: 0 +Default value: None +Accept pipeline input: True (ByValue) +Accept wildcard characters: False +``` + +### -VMName + +Specifies the name of the virtual machine to which the device is to be assigned. + +```yaml +Type: String[] +Parameter Sets: VMName +Aliases: + +Required: True +Position: 0 +Default value: None +Accept pipeline input: False +Accept wildcard characters: False +``` + +### -Confirm + +Prompts you for confirmation before running the cmdlet. + +```yaml +Type: SwitchParameter +Parameter Sets: (All) +Aliases: cf + +Required: False +Position: Named +Default value: None +Accept pipeline input: False +Accept wildcard characters: False +``` + +### -WhatIf + +Shows what would happen if the cmdlet runs. The cmdlet is not run. + +```yaml +Type: SwitchParameter +Parameter Sets: (All) +Aliases: wi + +Required: False +Position: Named +Default value: None +Accept pipeline input: False +Accept wildcard characters: False +``` + +### CommonParameters + +This cmdlet supports the common parameters: -Debug, -ErrorAction, -ErrorVariable, +-InformationAction, -InformationVariable, -OutVariable, -OutBuffer, -PipelineVariable, -Verbose, +-WarningAction, and -WarningVariable. For more information, see +[about_CommonParameters](/powershell/module/microsoft.powershell.core/about/about_commonparameters). + +## INPUTS + +### Microsoft.HyperV.PowerShell.VirtualMachine[] + +## OUTPUTS + +### Microsoft.HyperV.PowerShell.VMAssignedDevice + +## NOTES + +## RELATED LINKS + +[Get-VMAssignableDevice](get-vmassignabledevice.md) + +[Remove-VMAssignableDevice](remove-vmassignabledevice.md) diff --git a/docset/winserver2022-ps/hyper-v/Add-VMGpuPartitionAdapter.md b/docset/winserver2022-ps/hyper-v/Add-VMGpuPartitionAdapter.md index e86a3aa1c8..db45b5514f 100644 --- a/docset/winserver2022-ps/hyper-v/Add-VMGpuPartitionAdapter.md +++ b/docset/winserver2022-ps/hyper-v/Add-VMGpuPartitionAdapter.md @@ -2,7 +2,7 @@ description: Adds a GPU partition adapter to a virtual machine. external help file: Microsoft.HyperV.PowerShell.Cmdlets.dll-Help.xml Module Name: Hyper-V -ms.date: 09/22/2022 +ms.date: 06/12/2024 online version: https://learn.microsoft.com/powershell/module/hyper-v/add-vmgpupartitionadapter?view=windowsserver2022-ps&wt.mc_id=ps-gethelp schema: 2.0.0 title: Add-VMGpuPartitionAdapter @@ -16,53 +16,62 @@ Adds a GPU partition adapter to a virtual machine. ## SYNTAX ### VMName (Default) + ``` Add-VMGpuPartitionAdapter [-CimSession ] [-ComputerName ] [-Credential ] [-VMName] [-Passthru] [-InstancePath ] [-MinPartitionVRAM ] [-MaxPartitionVRAM ] [-OptimalPartitionVRAM ] [-MinPartitionEncode ] [-MaxPartitionEncode ] [-OptimalPartitionEncode ] [-MinPartitionDecode ] [-MaxPartitionDecode ] [-OptimalPartitionDecode ] - [-MinPartitionCompute ] [-MaxPartitionCompute ] [-OptimalPartitionCompute ] [-WhatIf] - [-Confirm] [] + [-MinPartitionCompute ] [-MaxPartitionCompute ] [-OptimalPartitionCompute ] + [-WhatIf] [-Confirm] [] ``` ### VMObject + ``` Add-VMGpuPartitionAdapter [-VM] [-Passthru] [-InstancePath ] [-MinPartitionVRAM ] [-MaxPartitionVRAM ] [-OptimalPartitionVRAM ] [-MinPartitionEncode ] [-MaxPartitionEncode ] [-OptimalPartitionEncode ] [-MinPartitionDecode ] [-MaxPartitionDecode ] [-OptimalPartitionDecode ] - [-MinPartitionCompute ] [-MaxPartitionCompute ] [-OptimalPartitionCompute ] [-WhatIf] - [-Confirm] [] + [-MinPartitionCompute ] [-MaxPartitionCompute ] [-OptimalPartitionCompute ] + [-WhatIf] [-Confirm] [] ``` ## DESCRIPTION -The 'Add-VMGpuPartitionAdapter' cmdlet adds a GPU partition adapter to a virtual machine. With no parameter, it assigns a full partition from an assignable GPU to a VM. + +The `Add-VMGpuPartitionAdapter` cmdlet adds a GPU partition adapter to a virtual machine. With no +parameter, it assigns a full partition from an assignable GPU to a VM. ## EXAMPLES ### Example 1 + ```powershell -$vm = Get-VM -name "TestVM" +$vm = Get-VM -Name "TestVM" Add-VMGpuPartitionAdapter -VM $vm ``` This example assigns a partition to a specific VM object. ### Example 2 + ```powershell -$vm = Get-VM -name "TestVM" -Add-VMGpuPartitionAdapter -VM $vm -Instancepath "SampleGPUInstancePath" +$vm = Get-VM -Name "TestVM" +Add-VMGpuPartitionAdapter -VM $vm -InstancePath "GPUInstancePath" ``` -This example assigns a partition from a specific GPU to a VM where the instance path is the GPU device ID name on the host. +This example assigns a partition from a specific GPU to a VM where the instance path is the GPU +device ID name on the host. ## PARAMETERS ### -CimSession -Runs the cmdlet in a remote session or on a remote computer. -Enter a computer name or a session object, such as the output of a [New-CimSession](https://go.microsoft.com/fwlink/p/?LinkId=227967) or [Get-CimSession](https://go.microsoft.com/fwlink/p/?LinkId=227966) cmdlet. -The default is the current session on the local computer. + +Runs the cmdlet in a remote session or on a remote computer. Enter a computer name or a session +object, such as the output of a [New-CimSession](/powershell/module/cimcmdlets/new-cimsession) +or [Get-CimSession](/powershell/module/cimcmdlets/get-cimsession) cmdlet. The default is the +current session on the local computer. ```yaml Type: CimSession[] @@ -77,10 +86,10 @@ Accept wildcard characters: False ``` ### -ComputerName -Specifies one or more Hyper-V hosts from which virtual machines are to be retrieved. -NetBIOS names, IP addresses, and fully qualified domain names are allowable. -The default is the local computer. -Use localhost or a dot ('.') to specify the local computer explicitly. + +Specifies one or more Hyper-V hosts from which virtual machines are to be retrieved. NetBIOS names, +IP addresses, and fully qualified domain names are allowable. The default is the local computer. +Use localhost or a dot (`.`) to specify the local computer explicitly. ```yaml Type: String[] @@ -95,8 +104,9 @@ Accept wildcard characters: False ``` ### -Credential -Specifies one or more user accounts that have permission to perform this action. -The default is the current user. + +Specifies one or more user accounts that have permission to perform this action. The default is the +current user. ```yaml Type: PSCredential[] @@ -111,7 +121,9 @@ Accept wildcard characters: False ``` ### -InstancePath -Represents the Device Instance path of a GPU in the host. This value can be obtained from the "Name" property of the command 'Get-VMHostPartitionableGpu'. + +Represents the Device Instance path of a GPU in the host. This value can be obtained from the +"Name" property of the command `Get-VMHostPartitionableGpu`. ```yaml Type: String @@ -126,7 +138,9 @@ Accept wildcard characters: False ``` ### -MaxPartitionCompute -The maximum number of compute assigned by the host GPU. This is defined by the manufacturer's driver. + +The maximum number of compute assigned by the host GPU. This is defined by the manufacturer's +driver. ```yaml Type: UInt64 @@ -141,7 +155,9 @@ Accept wildcard characters: False ``` ### -MaxPartitionDecode -The maximum number of decoders assigned by the host GPU. This is defined by the manufacturer's driver. + +The maximum number of decoders assigned by the host GPU. This is defined by the manufacturer's +driver. ```yaml Type: UInt64 @@ -156,7 +172,9 @@ Accept wildcard characters: False ``` ### -MaxPartitionEncode -The maximum number of encoders assigned by the host GPU. This is defined by the manufacturer's driver. + +The maximum number of encoders assigned by the host GPU. This is defined by the manufacturer's +driver. ```yaml Type: UInt64 @@ -171,6 +189,7 @@ Accept wildcard characters: False ``` ### -MaxPartitionVRAM + The maximum VRAM in bytes supported by the host GPU. This is defined by the manufacturer's driver. ```yaml @@ -186,7 +205,9 @@ Accept wildcard characters: False ``` ### -MinPartitionCompute -The minimum number of compute assigned by the host GPU. This is defined by the manufacturer's driver. + +The minimum number of compute assigned by the host GPU. This is defined by the manufacturer's +driver. ```yaml Type: UInt64 @@ -201,7 +222,9 @@ Accept wildcard characters: False ``` ### -MinPartitionDecode -The minimum number of decoders assigned by the host GPU. This is defined by the manufacturer's driver. + +The minimum number of decoders assigned by the host GPU. This is defined by the manufacturer's +driver. ```yaml Type: UInt64 @@ -216,7 +239,9 @@ Accept wildcard characters: False ``` ### -MinPartitionEncode -The minimum number of encoders assigned by the host GPU. This is defined by the manufacturer's driver. + +The minimum number of encoders assigned by the host GPU. This is defined by the manufacturer's +driver. ```yaml Type: UInt64 @@ -231,6 +256,7 @@ Accept wildcard characters: False ``` ### -MinPartitionVRAM + The minimum VRAM in bytes supported by the host GPU. This is defined by the manufacturer's driver. ```yaml @@ -246,7 +272,9 @@ Accept wildcard characters: False ``` ### -OptimalPartitionCompute -The optimal number of compute assigned by the host GPU. This is defined by the manufacturer's driver. + +The optimal number of compute assigned by the host GPU. This is defined by the manufacturer's +driver. ```yaml Type: UInt64 @@ -261,7 +289,9 @@ Accept wildcard characters: False ``` ### -OptimalPartitionDecode -The optimal number of decoders assigned by the host GPU. This is defined by the manufacturer's driver. + +The optimal number of decoders assigned by the host GPU. This is defined by the manufacturer's +driver. ```yaml Type: UInt64 @@ -276,7 +306,9 @@ Accept wildcard characters: False ``` ### -OptimalPartitionEncode -The optimal number of encoders assigned by the host GPU. This is defined by the manufacturer's driver. + +The optimal number of encoders assigned by the host GPU. This is defined by the manufacturer's +driver. ```yaml Type: UInt64 @@ -291,6 +323,7 @@ Accept wildcard characters: False ``` ### -OptimalPartitionVRAM + The optimal VRAM in bytes supported by the host GPU. This is defined by the manufacturer's driver. ```yaml @@ -306,6 +339,7 @@ Accept wildcard characters: False ``` ### -Passthru + Returns an object for each process that the cmdlet started. ```yaml @@ -321,6 +355,7 @@ Accept wildcard characters: False ``` ### -VM + Specifies the virtual machine on which the network adapter is to be added. ```yaml @@ -336,6 +371,7 @@ Accept wildcard characters: False ``` ### -VMName + Specifies the name of the virtual machine on which the network adapter is to be added. ```yaml @@ -351,6 +387,7 @@ Accept wildcard characters: False ``` ### -Confirm + Prompts you for confirmation before running the cmdlet. ```yaml @@ -366,8 +403,8 @@ Accept wildcard characters: False ``` ### -WhatIf -Shows what would happen if the cmdlet runs. -The cmdlet is not run. + +Shows what would happen if the cmdlet runs. The cmdlet is not run. ```yaml Type: SwitchParameter @@ -382,7 +419,11 @@ Accept wildcard characters: False ``` ### CommonParameters -This cmdlet supports the common parameters: -Debug, -ErrorAction, -ErrorVariable, -InformationAction, -InformationVariable, -OutVariable, -OutBuffer, -PipelineVariable, -Verbose, -WarningAction, and -WarningVariable. For more information, see [about_CommonParameters](https://go.microsoft.com/fwlink/?LinkID=113216). + +This cmdlet supports the common parameters: -Debug, -ErrorAction, -ErrorVariable, +-InformationAction, -InformationVariable, -OutVariable, -OutBuffer, -PipelineVariable, -Verbose, +-WarningAction, and -WarningVariable. For more information, see +[about_CommonParameters](/powershell/module/microsoft.powershell.core/about/about_commonparameters). ## INPUTS @@ -397,3 +438,9 @@ This cmdlet supports the common parameters: -Debug, -ErrorAction, -ErrorVariable ## NOTES ## RELATED LINKS + +[Get-VMGpuPartitionAdapter](get-vmgpupartitionadapter.md) + +[Remove-VMGpuPartitionAdapter](remove-vmgpupartitionadapter.md) + +[Set-VMGpuPartitionAdapter](set-vmgpupartitionadapter.md) diff --git a/docset/winserver2022-ps/hyper-v/Add-VMHostAssignableDevice.md b/docset/winserver2022-ps/hyper-v/Add-VMHostAssignableDevice.md new file mode 100644 index 0000000000..efd17eaf02 --- /dev/null +++ b/docset/winserver2022-ps/hyper-v/Add-VMHostAssignableDevice.md @@ -0,0 +1,216 @@ +--- +description: Assigns a device to a virtual machine host. +external help file: Microsoft.HyperV.PowerShell.Cmdlets.dll-Help.xml +Module Name: Hyper-V +ms.date: 06/12/2024 +online version: https://learn.microsoft.com/powershell/module/hyper-v/add-vmhostassignabledevice?view=windowsserver2022-ps&wt.mc_id=ps-gethelp +schema: 2.0.0 +title: Add-VMHostAssignableDevice +--- + +# Add-VMHostAssignableDevice + +## SYNOPSIS +Adds an assignable device to a virtual machine (VM) host. + +## SYNTAX + +### Path (Default) + +``` +Add-VMHostAssignableDevice [-CimSession ] [-ComputerName ] + [-Credential ] [-Force] [-InstancePath ] [-LocationPath ] + -ResourcePoolName [] +``` + +### Object + +``` +Add-VMHostAssignableDevice [-Force] [-HostAssignableDevice] + -ResourcePoolName [] +``` + +## DESCRIPTION + +The `Add-VMHostAssignableDevice` cmdlet assigns a hardware device to a virtual machine host. You +can add devices to the VM host by providing either the instance or location path of the device, or +by specifying an existing host-assignable device object. + +## EXAMPLES + +### Example 1 + +```powershell +$params = @{ +ComputerName = "MyVM01" +InstancePath = "PCI\VEN_8086&DEV_0F48&SUBSYS_72708086&REV_0B\3&11583659&0&D8" +ResourcePoolName = "MyResourcePool" +} +Add-VMHostAssignableDevice $params +``` + +This example assigns a device identified by its instance path to VM host **MyVM01** within the +resource pool **MyResourcePool**. + +## PARAMETERS + +### -CimSession + +Runs the cmdlet in a remote session or on a remote computer. Enter a computer name or a session +object, such as the output of a [New-CimSession](/powershell/module/cimcmdlets/new-cimsession) +or [Get-CimSession](/powershell/module/cimcmdlets/get-cimsession) cmdlet. The default is the +current session on the local computer. + +```yaml +Type: CimSession[] +Parameter Sets: Path +Aliases: + +Required: False +Position: Named +Default value: None +Accept pipeline input: False +Accept wildcard characters: False +``` + +### -ComputerName + +Specifies the name of the Hyper-V host to which the device is to be added. NetBIOS names, IP +addresses, and fully qualified domain names are allowed. The default is the local computer. Use +localhost or a dot (`.`) to specify the local computer explicitly. + +```yaml +Type: String[] +Parameter Sets: Path +Aliases: + +Required: False +Position: Named +Default value: None +Accept pipeline input: False +Accept wildcard characters: False +``` + +### -Credential + +Specifies one or more user accounts that have permission to perform this action. The default is the +current user. + +```yaml +Type: PSCredential[] +Parameter Sets: Path +Aliases: + +Required: False +Position: Named +Default value: None +Accept pipeline input: False +Accept wildcard characters: False +``` + +### -Force + +Forces the command to run without asking for user confirmation. + +```yaml +Type: SwitchParameter +Parameter Sets: (All) +Aliases: + +Required: False +Position: Named +Default value: None +Accept pipeline input: False +Accept wildcard characters: False +``` + +### -HostAssignableDevice + +Specifies the device object to be assigned to the virtual machine. + +```yaml +Type: VMHostAssignableDevice[] +Parameter Sets: Object +Aliases: VMHostAssignableDevice + +Required: True +Position: 0 +Default value: None +Accept pipeline input: True (ByValue) +Accept wildcard characters: False +``` + +### -InstancePath + +Represents the Device Instance path in the host machine. + +```yaml +Type: String +Parameter Sets: Path +Aliases: + +Required: False +Position: Named +Default value: None +Accept pipeline input: False +Accept wildcard characters: False +``` + +### -LocationPath + +Specifies the location path to the assignable device. + +```yaml +Type: String +Parameter Sets: Path +Aliases: + +Required: False +Position: Named +Default value: None +Accept pipeline input: False +Accept wildcard characters: False +``` + +### -ResourcePoolName + +Specifies the name of the resource pool to which the device is assigned. + +```yaml +Type: String[] +Parameter Sets: (All) +Aliases: + +Required: True +Position: Named +Default value: None +Accept pipeline input: False +Accept wildcard characters: False +``` + +### CommonParameters + +This cmdlet supports the common parameters: -Debug, -ErrorAction, -ErrorVariable, +-InformationAction, -InformationVariable, -OutVariable, -OutBuffer, -PipelineVariable, -Verbose, +-WarningAction, and -WarningVariable. For more information, see +[about_CommonParameters](/powershell/module/microsoft.powershell.core/about/about_commonparameters). + +## INPUTS + +### Microsoft.HyperV.PowerShell.VMHostAssignableDevice[] + +## OUTPUTS + +### System.Object + +## NOTES + +## RELATED LINKS + +[Get-VMHostAssignableDevice](get-vmhostassignabledevice.md) + +[Dismount-VMHostAssignableDevice](dismount-vmhostassignabledevice.md) + +[Mount-VMHostAssignableDevice](mount-vmhostassignabledevice.md) + +[Remove-VMHostAssignableDevice](remove-vmhostassignabledevice.md) diff --git a/docset/winserver2022-ps/hyper-v/Dismount-VMHostAssignableDevice.md b/docset/winserver2022-ps/hyper-v/Dismount-VMHostAssignableDevice.md new file mode 100644 index 0000000000..a2853e7371 --- /dev/null +++ b/docset/winserver2022-ps/hyper-v/Dismount-VMHostAssignableDevice.md @@ -0,0 +1,225 @@ +--- +description: Dismounts an assignable device from a virtual machine host. +external help file: Microsoft.HyperV.PowerShell.Cmdlets.dll-Help.xml +Module Name: Hyper-V +ms.date: 06/12/2024 +online version: https://learn.microsoft.com/powershell/module/hyper-v/dismount-vmhostassignabledevice?view=windowsserver2022-ps&wt.mc_id=ps-gethelp +schema: 2.0.0 +title: Dismount-VMHostAssignableDevice +--- + +# Dismount-VMHostAssignableDevice + +## SYNOPSIS +Dismounts a device from a virtual machine (VM) host. + +## SYNTAX + +``` +Dismount-VMHostAssignableDevice [-InstancePath ] [-LocationPath ] [-Force] + [-Passthru] [-CimSession ] [-ComputerName ] [-Credential ] + [-WhatIf] [-Confirm] [] +``` + +## DESCRIPTION + +The `Dismount-VMHostAssignableDevice` cmdlet is used to dismount an assignable device from the +virtual machine host. Use this cmdlet when you need to reassign a device or resolve conflicts +between devices and virtual machines. + +## EXAMPLES + +### Example 1 + +```powershell +Dismount-VMHostAssignableDevice -InstancePath "PCIROOT(0)#PCI(1D02)#PCI(0000)" +``` + +This example dismounts the device with the specified instance path from the host, making it +available for assignment to a virtual machine. + +## PARAMETERS + +### -CimSession + +Runs the cmdlet in a remote session or on a remote computer. Enter a computer name or a session +object, such as the output of a [New-CimSession](/powershell/module/cimcmdlets/new-cimsession) +or [Get-CimSession](/powershell/module/cimcmdlets/get-cimsession) cmdlet. The default is the +current session on the local computer. + +```yaml +Type: CimSession[] +Parameter Sets: (All) +Aliases: + +Required: False +Position: Named +Default value: None +Accept pipeline input: False +Accept wildcard characters: False +``` + +### -ComputerName + +Specifies one or more Hyper-V hosts from which the assignable devices are to be dismounted. NetBIOS +names, IP addresses, and fully qualified domain names are allowed. The default is the local +computer. Use localhost or a dot (`.`) to specify the local computer explicitly. + +```yaml +Type: String[] +Parameter Sets: Path +Aliases: + +Required: False +Position: Named +Default value: None +Accept pipeline input: False +Accept wildcard characters: False +``` + +### -Credential + +Specifies one or more user accounts that have permission to perform this action. The default is the +current user. + +```yaml +Type: PSCredential[] +Parameter Sets: (All) +Aliases: + +Required: False +Position: Named +Default value: None +Accept pipeline input: False +Accept wildcard characters: False +``` + +### -Force + +Forces the command to run without asking for user confirmation. + +Using the **Force** parameter also overrides some security checks in the platform. To learn more, +see [Dismount the device from the host partition +](/windows-server/virtualization/hyper-v/deploy/deploying-graphics-devices-using-dda#dismount-the-device-from-the-host-partition). + +If no partitioning driver is provided, during dismount, you must use `-Force` to bypass the +security warning. For more information about the security implications, see [Plan for deploying devices by using Discrete Device Assignment](/windows-server/virtualization/hyper-v/plan/plan-for-deploying-devices-using-discrete-device-assignment). + +```yaml +Type: SwitchParameter +Parameter Sets: (All) +Aliases: + +Required: False +Position: Named +Default value: None +Accept pipeline input: False +Accept wildcard characters: False +``` + +### -InstancePath + +Represents the Device Instance path in the host machine. + +```yaml +Type: String +Parameter Sets: (All) +Aliases: + +Required: False +Position: Named +Default value: None +Accept pipeline input: False +Accept wildcard characters: False +``` + +### -LocationPath + +Specifies the location path to the assignable device. + +```yaml +Type: String +Parameter Sets: (All) +Aliases: + +Required: False +Position: Named +Default value: None +Accept pipeline input: False +Accept wildcard characters: False +``` + +### -Passthru + +Returns an object for each process that the cmdlet started. + +```yaml +Type: SwitchParameter +Parameter Sets: (All) +Aliases: + +Required: False +Position: Named +Default value: None +Accept pipeline input: False +Accept wildcard characters: False +``` + +### -Confirm + +Prompts you for confirmation before running the cmdlet. + +```yaml +Type: SwitchParameter +Parameter Sets: (All) +Aliases: cf + +Required: False +Position: Named +Default value: None +Accept pipeline input: False +Accept wildcard characters: False +``` + +### -WhatIf + +Shows what would happen if the cmdlet runs. The cmdlet is not run. + +```yaml +Type: SwitchParameter +Parameter Sets: (All) +Aliases: wi + +Required: False +Position: Named +Default value: None +Accept pipeline input: False +Accept wildcard characters: False +``` + +### CommonParameters + +This cmdlet supports the common parameters: -Debug, -ErrorAction, -ErrorVariable, +-InformationAction, -InformationVariable, -OutVariable, -OutBuffer, -PipelineVariable, -Verbose, +-WarningAction, and -WarningVariable. For more information, see +[about_CommonParameters](/powershell/module/microsoft.powershell.core/about/about_commonparameters). + +## INPUTS + +### None + +## OUTPUTS + +### Microsoft.HyperV.PowerShell.VMHostAssignableDevice + +## NOTES + +## RELATED LINKS + +[Add-VMHostAssignableDevice](add-vmhostassignabledevice.md) + +[Get-VMHostAssignableDevice](get-vmhostassignabledevice.md) + +[Mount-VMHostAssignableDevice](mount-vmhostassignabledevice.md) + +[Remove-VMHostAssignableDevice](remove-vmhostassignabledevice.md) diff --git a/docset/winserver2022-ps/hyper-v/Get-VMAssignableDevice.md b/docset/winserver2022-ps/hyper-v/Get-VMAssignableDevice.md new file mode 100644 index 0000000000..d1d868253e --- /dev/null +++ b/docset/winserver2022-ps/hyper-v/Get-VMAssignableDevice.md @@ -0,0 +1,194 @@ +--- +description: Retrieves information about a device assigned to a virtual machine. +external help file: Microsoft.HyperV.PowerShell.Cmdlets.dll-Help.xml +Module Name: Hyper-V +ms.date: 06/12/2024 +online version: https://learn.microsoft.com/powershell/module/hyper-v/get-vmassignabledevice?view=windowsserver2022-ps&wt.mc_id=ps-gethelp +schema: 2.0.0 +title: Get-VMAssignableDevice +--- + +# Get-VMAssignableDevice + +## SYNOPSIS +Retrieves information about the assignable device from a specific virtual machine. + +## SYNTAX + +### VMName (Default) + +``` +Get-VMAssignableDevice [-CimSession ] [-ComputerName ] + [-Credential ] [-VMName] [-InstancePath ] + [-LocationPath ] [] +``` + +### VMObject + +``` +Get-VMAssignableDevice [-VM] [-InstancePath ] [-LocationPath ] + [] +``` + +## DESCRIPTION + +The `Get-VMAssignableDevice` cmdlet retrieves information about the assignable devices that are +associated with a specific virtual machine (VM). This cmdlet can be used to list all assignable +devices that can be attached to a VM or to retrieve details about specific devices that are already +assigned. The retrieved information can include the device's instance path, location path, and +other relevant properties. + +## EXAMPLES + +### Example 1 + +```powershell +Get-VMAssignableDevice -VMName "MyVM" +``` + +This example retrieves all assignable devices associated with the virtual machine named **MyVM**. + +## PARAMETERS + +### -CimSession + +Runs the cmdlet in a remote session or on a remote computer. Enter a computer name or a session +object, such as the output of a [New-CimSession](/powershell/module/cimcmdlets/new-cimsession) +or [Get-CimSession](/powershell/module/cimcmdlets/get-cimsession) cmdlet. The default is the +current session on the local computer. + +```yaml +Type: CimSession[] +Parameter Sets: VMName +Aliases: + +Required: False +Position: Named +Default value: None +Accept pipeline input: False +Accept wildcard characters: False +``` + +### -ComputerName + +Specifies one or more Hyper-V hosts from which the assignable devices are to be retrieved. NetBIOS +names, IP addresses, and fully qualified domain names are allowed. The default is the local +computer. Use localhost or a dot (`.`) to specify the local computer explicitly. + +```yaml +Type: String[] +Parameter Sets: VMName +Aliases: + +Required: False +Position: Named +Default value: None +Accept pipeline input: False +Accept wildcard characters: False +``` + +### -Credential + +Retrieves one or more user accounts that have permission to perform this action. The default is the +current user. + +```yaml +Type: PSCredential[] +Parameter Sets: VMName +Aliases: + +Required: False +Position: Named +Default value: None +Accept pipeline input: False +Accept wildcard characters: False +``` + +### -InstancePath + +Represents the Device Instance path in the host machine. + +```yaml +Type: String +Parameter Sets: (All) +Aliases: + +Required: False +Position: Named +Default value: None +Accept pipeline input: False +Accept wildcard characters: False +``` + +### -LocationPath + +Specifies the location path to the assignable device + +```yaml +Type: String +Parameter Sets: (All) +Aliases: + +Required: False +Position: Named +Default value: None +Accept pipeline input: False +Accept wildcard characters: False +``` + +### -VM + +Retrieves the virtual machine which a device is assigned. + +```yaml +Type: VirtualMachine[] +Parameter Sets: VMObject +Aliases: + +Required: True +Position: 0 +Default value: None +Accept pipeline input: True (ByValue) +Accept wildcard characters: False +``` + +### -VMName + +Retrieves the names of the assignable devices assigned to the specified virtual machine. + +```yaml +Type: String[] +Parameter Sets: VMName +Aliases: + +Required: True +Position: 0 +Default value: None +Accept pipeline input: True (ByValue) +Accept wildcard characters: False +``` + +### CommonParameters + +This cmdlet supports the common parameters: -Debug, -ErrorAction, -ErrorVariable, +-InformationAction, -InformationVariable, -OutVariable, -OutBuffer, -PipelineVariable, -Verbose, +-WarningAction, and -WarningVariable. For more information, see +[about_CommonParameters](/powershell/module/microsoft.powershell.core/about/about_commonparameters). + +## INPUTS + +### System.String[] + +### Microsoft.HyperV.PowerShell.VirtualMachine[] + +## OUTPUTS + +### Microsoft.HyperV.PowerShell.VMAssignedDevice + +## NOTES + +## RELATED LINKS + +[Add-VMAssignableDevice](add-vmassignabledevice.md) + +[Remove-VMAssignableDevice](remove-vmassignabledevice.md) diff --git a/docset/winserver2022-ps/hyper-v/Get-VMGpuPartitionAdapter.md b/docset/winserver2022-ps/hyper-v/Get-VMGpuPartitionAdapter.md index 5df16d8162..ac4dfa9373 100644 --- a/docset/winserver2022-ps/hyper-v/Get-VMGpuPartitionAdapter.md +++ b/docset/winserver2022-ps/hyper-v/Get-VMGpuPartitionAdapter.md @@ -2,7 +2,7 @@ description: Gets the information of assigned GPU partitions to a virtual machine. external help file: Microsoft.HyperV.PowerShell.Cmdlets.dll-Help.xml Module Name: Hyper-V -ms.date: 09/22/2022 +ms.date: 06/12/2024 online version: https://learn.microsoft.com/powershell/module/hyper-v/get-vmgpupartitionadapter?view=windowsserver2022-ps&wt.mc_id=ps-gethelp schema: 2.0.0 title: Get-VMGpuPartitionAdapter @@ -16,24 +16,29 @@ Gets the information of assigned GPU partitions to a virtual machine. ## SYNTAX ### VMName (Default) + ``` Get-VMGpuPartitionAdapter [-CimSession ] [-ComputerName ] [-Credential ] [-VMName] [-AdapterId ] [] ``` ### VMObject + ``` Get-VMGpuPartitionAdapter [-VM] [-AdapterId ] [] ``` ## DESCRIPTION -The 'Get-VMGpuPartitionAdapter' cmdlet gets the information of assigned graphic processing unit partitions to a virtual machine. + +The `Get-VMGpuPartitionAdapter` cmdlet gets the information of assigned graphic processing unit +partitions to a virtual machine. ## EXAMPLES ### Example 1 + ```powershell -$testvm = get-VM "TestVM" +$testvm = Get-VM "TestVM" Get-VMGpuPartitionAdapter -VM $testvm ``` @@ -42,7 +47,9 @@ This example gets the GPU information assigned to a VM object. ## PARAMETERS ### -AdapterId -This is a VM's GPU partition identification number used to display the GPU information assigned to a VM. + +This is a VM's GPU partition identification number used to display the GPU information assigned to a +VM. ```yaml Type: String @@ -57,9 +64,11 @@ Accept wildcard characters: False ``` ### -CimSession -Runs the cmdlet in a remote session or on a remote computer. -Enter a computer name or a session object, such as the output of a [New-CimSession](https://go.microsoft.com/fwlink/p/?LinkId=227967) or [Get-CimSession](https://go.microsoft.com/fwlink/p/?LinkId=227966) cmdlet. -The default is the current session on the local computer. + +Runs the cmdlet in a remote session or on a remote computer. Enter a computer name or a session +object, such as the output of a [New-CimSession](/powershell/module/cimcmdlets/new-cimsession) +or [Get-CimSession](/powershell/module/cimcmdlets/get-cimsession) cmdlet. The default is the +current session on the local computer. ```yaml Type: CimSession[] @@ -74,10 +83,10 @@ Accept wildcard characters: False ``` ### -ComputerName -Specifies one or more Hyper-V hosts on the virtual network adapters are to be retrieved. -NetBIOS names, IP addresses, and fully qualified domain names are allowed. -The default is the local computer. -Use localhost or a dot ('.') to specify the local computer explicitly. + +Specifies one or more Hyper-V hosts on the virtual network adapters are to be retrieved. NetBIOS +names, IP addresses, and fully qualified domain names are allowed. The default is the local +computer. Use localhost or a dot (`.`) to specify the local computer explicitly. ```yaml Type: String[] @@ -92,8 +101,9 @@ Accept wildcard characters: False ``` ### -Credential -Specifies one or more user accounts that have permission to perform this action. -The default is the current user. + +Specifies one or more user accounts that have permission to perform this action. The default is the +current user. ```yaml Type: PSCredential[] @@ -108,6 +118,7 @@ Accept wildcard characters: False ``` ### -VM + Specifies the virtual machine whose virtual network adapters are to be retrieved. The asterisk (`*`) is the wildcard. If it is specified the cmdlet returns virtual network adapters from every virtual machine in the system. @@ -125,6 +136,7 @@ Accept wildcard characters: True ``` ### -VMName + Specifies the name of the virtual machine whose network adapters are to be retrieved. ```yaml @@ -140,7 +152,11 @@ Accept wildcard characters: False ``` ### CommonParameters -This cmdlet supports the common parameters: -Debug, -ErrorAction, -ErrorVariable, -InformationAction, -InformationVariable, -OutVariable, -OutBuffer, -PipelineVariable, -Verbose, -WarningAction, and -WarningVariable. For more information, see [about_CommonParameters](https://go.microsoft.com/fwlink/?LinkID=113216). + +This cmdlet supports the common parameters: -Debug, -ErrorAction, -ErrorVariable, +-InformationAction, -InformationVariable, -OutVariable, -OutBuffer, -PipelineVariable, -Verbose, +-WarningAction, and -WarningVariable. For more information, see +[about_CommonParameters](/powershell/module/microsoft.powershell.core/about/about_commonparameters). ## INPUTS @@ -155,3 +171,9 @@ This cmdlet supports the common parameters: -Debug, -ErrorAction, -ErrorVariable ## NOTES ## RELATED LINKS + +[Add-VMGpuPartitionAdapter](add-vmgpupartitionadapter.md) + +[Remove-VMGpuPartitionAdapter](remove-vmgpupartitionadapter.md) + +[Set-VMGpuPartitionAdapter](set-vmgpupartitionadapter.md) diff --git a/docset/winserver2022-ps/hyper-v/Get-VMHostAssignableDevice.md b/docset/winserver2022-ps/hyper-v/Get-VMHostAssignableDevice.md new file mode 100644 index 0000000000..21710a4e47 --- /dev/null +++ b/docset/winserver2022-ps/hyper-v/Get-VMHostAssignableDevice.md @@ -0,0 +1,178 @@ +--- +description: Retrieves information about an assignable device to a virtual machine host. +external help file: Microsoft.HyperV.PowerShell.Cmdlets.dll-Help.xml +Module Name: Hyper-V +ms.date: 06/12/2024 +online version: https://learn.microsoft.com/powershell/module/hyper-v/get-vmhostassignabledevice?view=windowsserver2022-ps&wt.mc_id=ps-gethelp +schema: 2.0.0 +title: Get-VMHostAssignableDevice +--- + +# Get-VMHostAssignableDevice + +## SYNOPSIS +Retrieves device information assigned to a virtual machine (VM) host. + +## SYNTAX + +``` +Get-VMHostAssignableDevice [-InstancePath ] [-LocationPath ] + [-ResourcePoolName ] [-CimSession ] [-ComputerName ] + [-Credential ] [] +``` + +## DESCRIPTION + +The `Get-VMHostAssignableDevice` cmdlet retrieves information about devices that can be assigned to +a virtual machine host. This can include devices such as GPUs, network adapters, or storage +controllers that are physically present on the host system. The cmdlet can filter devices by their +instance path or location path. + +## EXAMPLES + +### Example 1 + +```powershell +Get-VMHostAssignableDevice +``` + +This example retrieves all assignable devices on the host computer. + +### Example 2 + +```powershell +Get-VMHostAssignableDevice -ComputerName "MyHost" +``` + +In this example, the cmdlet retrieves all assignable devices from the computer named **MyHost**. + +## PARAMETERS + +### -CimSession + +Runs the cmdlet in a remote session or on a remote computer. Enter a computer name or a session +object, such as the output of a [New-CimSession](/powershell/module/cimcmdlets/new-cimsession) +or [Get-CimSession](/powershell/module/cimcmdlets/get-cimsession) cmdlet. The default is the +current session on the local computer. + +```yaml +Type: CimSession[] +Parameter Sets: (All) +Aliases: + +Required: False +Position: Named +Default value: None +Accept pipeline input: False +Accept wildcard characters: False +``` + +### -ComputerName + +Specifies one or more Hyper-V hosts from which the assignable devices are to be retrieved. NetBIOS +names, IP addresses, and fully qualified domain names are allowed. The default is the local +computer. Use localhost or a dot (`.`) to specify the local computer explicitly. + +```yaml +Type: String[] +Parameter Sets: (All) +Aliases: + +Required: False +Position: Named +Default value: None +Accept pipeline input: False +Accept wildcard characters: False +``` + +### -Credential + +Specifies one or more user accounts that have permission to perform this action. The default is the +current user. + +```yaml +Type: PSCredential[] +Parameter Sets: (All) +Aliases: + +Required: False +Position: Named +Default value: None +Accept pipeline input: False +Accept wildcard characters: False +``` + +### -InstancePath + +Represents the Device Instance path in the host machine. + +```yaml +Type: String +Parameter Sets: (All) +Aliases: + +Required: False +Position: Named +Default value: None +Accept pipeline input: False +Accept wildcard characters: False +``` + +### -LocationPath + +Specifies the location path to the assignable device. + +```yaml +Type: String +Parameter Sets: (All) +Aliases: + +Required: False +Position: Named +Default value: None +Accept pipeline input: False +Accept wildcard characters: False +``` + +### -ResourcePoolName + +Retrieves the name of the resource pool to which the device is assigned. + +```yaml +Type: String[] +Parameter Sets: (All) +Aliases: + +Required: False +Position: Named +Default value: None +Accept pipeline input: False +Accept wildcard characters: False +``` + +### CommonParameters + +This cmdlet supports the common parameters: -Debug, -ErrorAction, -ErrorVariable, +-InformationAction, -InformationVariable, -OutVariable, -OutBuffer, -PipelineVariable, -Verbose, +-WarningAction, and -WarningVariable. For more information, see +[about_CommonParameters](/powershell/module/microsoft.powershell.core/about/about_commonparameters). + +## INPUTS + +### None + +## OUTPUTS + +### Microsoft.HyperV.PowerShell.VMHostAssignableDevice + +## NOTES + +## RELATED LINKS + +[Add-VMHostAssignableDevice](add-vmhostassignabledevice.md) + +[Dismount-VMHostAssignableDevice](dismount-vmhostassignabledevice.md) + +[Mount-VMHostAssignableDevice](mount-vmhostassignabledevice.md) + +[Remove-VMHostAssignableDevice](remove-vmhostassignabledevice.md) diff --git a/docset/winserver2022-ps/hyper-v/Get-VMHostPartitionableGpu.md b/docset/winserver2022-ps/hyper-v/Get-VMHostPartitionableGpu.md index c22e441be3..21c54739a9 100644 --- a/docset/winserver2022-ps/hyper-v/Get-VMHostPartitionableGpu.md +++ b/docset/winserver2022-ps/hyper-v/Get-VMHostPartitionableGpu.md @@ -2,7 +2,7 @@ description: Gets the host machine’s partitionable GPU. external help file: Microsoft.HyperV.PowerShell.Cmdlets.dll-Help.xml Module Name: Hyper-V -ms.date: 09/22/2022 +ms.date: 06/12/2024 online version: https://learn.microsoft.com/powershell/module/hyper-v/get-vmhostpartitionablegpu?view=windowsserver2022-ps&wt.mc_id=ps-gethelp schema: 2.0.0 title: Get-VMHostPartitionableGpu @@ -16,49 +16,59 @@ Gets the host machine’s partitionable GPU. ## SYNTAX ### ComputerName (Default) + ``` -Get-VMHostPartitionableGpu [[-ComputerName] ] [[-Credential] ] [-Name ] - [] +Get-VMHostPartitionableGpu [[-ComputerName] ] [[-Credential] ] + [-Name ] [] ``` ### CimSession + ``` Get-VMHostPartitionableGpu [-CimSession] [-Name ] [] ``` ## DESCRIPTION -The 'Get-VMHostPartitionableGpu' cmdlet gets the host machine’s partitionable graphic processing unit. -This displays the information of the GPU as provided by the manufacturer's driver. + +The `Get-VMHostPartitionableGpu` cmdlet gets the host machine’s partitionable graphic processing +unit. This displays the information of the GPU as provided by the manufacturer's driver. ## EXAMPLES ### Example 1 -``` + +```powershell Get-VMHostPartitionableGpu ``` This example gets the details of the local partitionable graphic processing unit on the host. ### Example 2 + ```powershell -Get-VMHostPartitionableGpu -ComputerName "SampleHost" +Get-VMHostPartitionableGpu -ComputerName "MyHost" ``` -This example gets a partitionable GPU by using the host name. This command will display all the GPU devices available for partitioning in the host. +This example gets a partitionable GPU by using the host name. This command will display all the GPU +devices available for partitioning in the host. ### Example 3 + ```powershell -Get-VMHostPartitionableGpu -name "SampleGPUDeviceIDName" +Get-VMHostPartitionableGpu -Name "GPUDeviceIDName" ``` -Displays a partitionable GPU by using the specific GPU device name. The result will show the details of the specific GPU listed. +Displays a partitionable GPU by using the specific GPU device name. The result will show the +details of the specific GPU listed. ## PARAMETERS ### -CimSession -Runs the cmdlet in a remote session or on a remote computer. -Enter a computer name or a session object, such as the output of a [New-CimSession](https://go.microsoft.com/fwlink/p/?LinkId=227967) or [Get-CimSession](https://go.microsoft.com/fwlink/p/?LinkId=227966) cmdlet. -The default is the current session on the local computer. + +Runs the cmdlet in a remote session or on a remote computer. Enter a computer name or a session +object, such as the output of a [New-CimSession](/powershell/module/cimcmdlets/new-cimsession) +or [Get-CimSession](/powershell/module/cimcmdlets/get-cimsession) cmdlet. The default is the +current session on the local computer. ```yaml Type: CimSession[] @@ -73,10 +83,10 @@ Accept wildcard characters: False ``` ### -ComputerName -Specifies one or more Hyper-V hosts that run this cmdlet. -NetBIOS names, IP addresses, and fully qualified domain names are allowed. -The default is the local computer. -Use localhost or a dot ('.') to specify the local computer explicitly. + +Specifies one or more Hyper-V hosts that run this cmdlet. NetBIOS names, IP addresses, and fully +qualified domain names are allowed. The default is the local computer. Use localhost or a dot (`.`) +to specify the local computer explicitly. ```yaml Type: String[] @@ -91,7 +101,9 @@ Accept wildcard characters: False ``` ### -Credential -Specifies one or more user accounts that have permission to perform this action. The default is the current user. + +Specifies one or more user accounts that have permission to perform this action. The default is the +current user. ```yaml Type: PSCredential[] @@ -106,6 +118,7 @@ Accept wildcard characters: False ``` ### -Name + Specifies the name of the graphic processing unit to be retrieved. ```yaml @@ -121,7 +134,11 @@ Accept wildcard characters: False ``` ### CommonParameters -This cmdlet supports the common parameters: -Debug, -ErrorAction, -ErrorVariable, -InformationAction, -InformationVariable, -OutVariable, -OutBuffer, -PipelineVariable, -Verbose, -WarningAction, and -WarningVariable. For more information, see [about_CommonParameters](https://go.microsoft.com/fwlink/?LinkID=113216). + +This cmdlet supports the common parameters: -Debug, -ErrorAction, -ErrorVariable, +-InformationAction, -InformationVariable, -OutVariable, -OutBuffer, -PipelineVariable, -Verbose, +-WarningAction, and -WarningVariable. For more information, see +[about_CommonParameters](/powershell/module/microsoft.powershell.core/about/about_commonparameters). ## INPUTS @@ -134,3 +151,5 @@ This cmdlet supports the common parameters: -Debug, -ErrorAction, -ErrorVariable ## NOTES ## RELATED LINKS + +[Set-VMHostPartitionableGpu](set-vmhostpartitionablegpu.md) diff --git a/docset/winserver2022-ps/hyper-v/Get-VMNetworkAdapter.md b/docset/winserver2022-ps/hyper-v/Get-VMNetworkAdapter.md index 42f8d2c5ae..8cc8748459 100644 --- a/docset/winserver2022-ps/hyper-v/Get-VMNetworkAdapter.md +++ b/docset/winserver2022-ps/hyper-v/Get-VMNetworkAdapter.md @@ -203,7 +203,7 @@ Accept wildcard characters: False ### -VM Specifies the virtual machine whose virtual network adapters are to be retrieved. -. The asterisk, "*", is the wildcard. +The asterisk, "*", is the wildcard. If it is specified the cmdlet returns virtual network adapters from every virtual machine in the system. ```yaml diff --git a/docset/winserver2022-ps/hyper-v/Hyper-V.md b/docset/winserver2022-ps/hyper-v/Hyper-V.md index d98210af0e..6e76f92be7 100644 --- a/docset/winserver2022-ps/hyper-v/Hyper-V.md +++ b/docset/winserver2022-ps/hyper-v/Hyper-V.md @@ -5,7 +5,7 @@ Help Version: 5.0.2.1 Locale: en-US Module Guid: af4bddd0-8583-4ff2-84b2-a33f5c8de8a7 Module Name: Hyper-V -ms.date: 12/20/2016 +ms.date: 06/12/2024 title: Hyper-V --- # Hyper-V Module @@ -16,6 +16,9 @@ This reference provides cmdlet descriptions and syntax for all Hyper-V-specific ## Hyper-V Cmdlets +### [Add-VMAssignableDevice](./Add-VMAssignableDevice.md) +Adds an assignable device to a specific virtual machine. + ### [Add-VMDvdDrive](./Add-VMDvdDrive.md) Adds a DVD drive to a virtual machine. @@ -31,6 +34,9 @@ Adds group members to a virtual machine group. ### [Add-VMHardDiskDrive](./Add-VMHardDiskDrive.md) Adds a hard disk drive to a virtual machine. +### [Add-VMHostAssignableDevice](./Add-VMHostAssignableDevice.md) +Adds an assignable device to a virtual machine (VM) host. + ### [Add-VMMigrationNetwork](./Add-VMMigrationNetwork.md) Adds a network for virtual machine migration on one or more virtual machine hosts. @@ -124,6 +130,9 @@ Removes a host bus adapter from a virtual storage area network (SAN). ### [Dismount-VHD](./Dismount-VHD.md) Dismounts a virtual hard disk. +### [Dismount-VMHostAssignableDevice](./Dismount-VMHostAssignableDevice.md) +Dismounts a device from a virtual machine (VM) host. + ### [Enable-VMConsoleSupport](./Enable-VMConsoleSupport.md) Enables keyboard, video, and mouse for virtual machines. @@ -169,6 +178,9 @@ Gets information about a checkpoint in a VHD set. ### [Get-VM](./Get-VM.md) Gets the virtual machines from one or more Hyper-V hosts. +### [Get-VMAssignableDevice](./Get-VMAssignableDevice.md) +Retrieves information about the assignable device from a specific virtual machine. + ### [Get-VMBios](./Get-VMBios.md) Gets the BIOS of a virtual machine or snapshot. @@ -202,6 +214,9 @@ Gets the virtual hard disk drives attached to one or more virtual machines. ### [Get-VMHost](./Get-VMHost.md) Gets a Hyper-V host. +### [Get-VMHostAssignableDevice](./Get-VMHostAssignableDevice.md) +Retrieves device information assigned to a virtual machine (VM) host. + ### [Get-VMHostCluster](./Get-VMHostCluster.md) Gets virtual machine host clusters. @@ -252,7 +267,6 @@ Gets members of a routing domain. ### [Get-VMNetworkAdapterTeamMapping](./Get-VMNetworkAdapterTeamMapping.md) - ### [Get-VMNetworkAdapterVlan](./Get-VMNetworkAdapterVlan.md) Gets the virtual LAN settings configured on a virtual network adapter. @@ -349,6 +363,9 @@ Merges virtual hard disks. ### [Mount-VHD](./Mount-VHD.md) Mounts one or more virtual hard disks. +### [Mount-VMHostAssignableDevice](./Mount-VMHostAssignableDevice.md) +Mounts a device to a virtual machine (VM) host. + ### [Move-VM](./Move-VM.md) Moves a virtual machine to a new Hyper-V host. @@ -391,6 +408,9 @@ Removes a checkpoint from a VHD set file. ### [Remove-VM](./Remove-VM.md) Deletes a virtual machine. +### [Remove-VMAssignableDevice](./Remove-VMAssignableDevice.md) +Removes information about the assignable devices from a specific virtual machine. + ### [Remove-VMDvdDrive](./Remove-VMDvdDrive.md) Deletes a DVD drive from a virtual machine. @@ -409,6 +429,9 @@ Removes members from a virtual machine group. ### [Remove-VMHardDiskDrive](./Remove-VMHardDiskDrive.md) Deletes a hard disk drive from a virtual machine. +### [Remove-VMHostAssignableDevice](./Remove-VMHostAssignableDevice.md) +Removes a device assigned to a virtual machine (VM) host. + ### [Remove-VMMigrationNetwork](./Remove-VMMigrationNetwork.md) Removes a network from use with migration. @@ -426,7 +449,6 @@ Removes a routing domain from a virtual network adapter. ### [Remove-VMNetworkAdapterTeamMapping](./Remove-VMNetworkAdapterTeamMapping.md) - ### [Remove-VMRemoteFx3dVideoAdapter](./Remove-VMRemoteFx3dVideoAdapter.md) Removes a RemoteFX 3D video adapter from a virtual machine. @@ -579,7 +601,6 @@ Sets virtual subnets on a routing domain. ### [Set-VMNetworkAdapterTeamMapping](./Set-VMNetworkAdapterTeamMapping.md) - ### [Set-VMNetworkAdapterVlan](./Set-VMNetworkAdapterVlan.md) Configures the virtual LAN settings for the traffic through a virtual network adapter. diff --git a/docset/winserver2022-ps/hyper-v/Mount-VMHostAssignableDevice.md b/docset/winserver2022-ps/hyper-v/Mount-VMHostAssignableDevice.md new file mode 100644 index 0000000000..f369872edc --- /dev/null +++ b/docset/winserver2022-ps/hyper-v/Mount-VMHostAssignableDevice.md @@ -0,0 +1,232 @@ +--- +description: Mounts an assignable device to a virtual machine host. +external help file: Microsoft.HyperV.PowerShell.Cmdlets.dll-Help.xml +Module Name: Hyper-V +ms.date: 06/12/2024 +online version: https://learn.microsoft.com/powershell/module/hyper-v/mount-vmhostassignabledevice?view=windowsserver2022-ps&wt.mc_id=ps-gethelp +schema: 2.0.0 +title: Mount-VMHostAssignableDevice +--- + +# Mount-VMHostAssignableDevice + +## SYNOPSIS +Mounts a device to a virtual machine (VM) host. + +## SYNTAX + +### Path (Default) + +``` +Mount-VMHostAssignableDevice [-CimSession ] [-ComputerName ] + [-Credential ] [-InstancePath ] [-LocationPath ] [-Passthru] + [-WhatIf] [-Confirm] [] +``` + +### Object + +``` +Mount-VMHostAssignableDevice [-HostAssignableDevice] [-Passthru] + [-WhatIf] [-Confirm] [] +``` + +## DESCRIPTION + +The `Mount-VMHostAssignableDevice` cmdlet mounts a device such as GPUs, network adapters, or storage +controllers that are physically present on the virtual machine host. + +## EXAMPLES + +### Example 1 + +```powershell +$device = Get-VMHostAssignableDevice -InstancePath "PCIROOT(0)#PCI(0300)#PCI(0000)" +$params = @{ +HostAssignableDevice = $device +VMName = "MyVM" +} +Mount-VMHostAssignableDevice @params +``` + +In this example, the `Get-VMHostAssignableDevice` cmdlet retrieves the device with the specified +instance path and stores it in the `$device` variable. The `Mount-VMHostAssignableDevice` cmdlet +then assigns this device to the virtual machine named **MyVM**. + +## PARAMETERS + +### -CimSession + +Runs the cmdlet in a remote session or on a remote computer. Enter a computer name or a session +object, such as the output of a [New-CimSession](/powershell/module/cimcmdlets/new-cimsession) +or [Get-CimSession](/powershell/module/cimcmdlets/get-cimsession) cmdlet. The default is the +current session on the local computer. + +```yaml +Type: CimSession[] +Parameter Sets: Path +Aliases: + +Required: False +Position: Named +Default value: None +Accept pipeline input: False +Accept wildcard characters: False +``` + +### -ComputerName + +Specifies one or more Hyper-V hosts from which the assignable devices are to be mounted. NetBIOS +names, IP addresses, and fully qualified domain names are allowed. The default is the local +computer. Use localhost or a dot (`.`) to specify the local computer explicitly. + +```yaml +Type: String[] +Parameter Sets: Path +Aliases: + +Required: False +Position: Named +Default value: None +Accept pipeline input: False +Accept wildcard characters: False +``` + +### -Credential + +Specifies one or more user accounts that have permission to perform this action. The default is the +current user. + +```yaml +Type: PSCredential[] +Parameter Sets: Path +Aliases: + +Required: False +Position: Named +Default value: None +Accept pipeline input: False +Accept wildcard characters: False +``` + +### -HostAssignableDevice + +Specifies the assignable device to be mounted on the virtual machine host. + +```yaml +Type: VMHostAssignableDevice[] +Parameter Sets: Object +Aliases: VMHostAssignableDevice + +Required: True +Position: 0 +Default value: None +Accept pipeline input: True (ByValue) +Accept wildcard characters: False +``` + +### -InstancePath + +Represents the Device Instance path in the host machine. + +```yaml +Type: String +Parameter Sets: Path +Aliases: + +Required: False +Position: Named +Default value: None +Accept pipeline input: False +Accept wildcard characters: False +``` + +### -LocationPath + +Specifies the location path to the assignable device. + +```yaml +Type: String +Parameter Sets: Path +Aliases: + +Required: False +Position: Named +Default value: None +Accept pipeline input: False +Accept wildcard characters: False +``` + +### -Passthru + +Returns an object for each process that the cmdlet started. + +```yaml +Type: SwitchParameter +Parameter Sets: (All) +Aliases: + +Required: False +Position: Named +Default value: None +Accept pipeline input: False +Accept wildcard characters: False +``` + +### -Confirm + +Prompts you for confirmation before running the cmdlet. + +```yaml +Type: SwitchParameter +Parameter Sets: (All) +Aliases: cf + +Required: False +Position: Named +Default value: None +Accept pipeline input: False +Accept wildcard characters: False +``` + +### -WhatIf + +Shows what would happen if the cmdlet runs. The cmdlet is not run. + +```yaml +Type: SwitchParameter +Parameter Sets: (All) +Aliases: wi + +Required: False +Position: Named +Default value: None +Accept pipeline input: False +Accept wildcard characters: False +``` + +### CommonParameters + +This cmdlet supports the common parameters: -Debug, -ErrorAction, -ErrorVariable, +-InformationAction, -InformationVariable, -OutVariable, -OutBuffer, -PipelineVariable, -Verbose, +-WarningAction, and -WarningVariable. For more information, see +[about_CommonParameters](/powershell/module/microsoft.powershell.core/about/about_commonparameters). + +## INPUTS + +### Microsoft.HyperV.PowerShell.VMHostAssignableDevice[] + +## OUTPUTS + +### Microsoft.HyperV.PowerShell.VMHostAssignableDevice + +## NOTES + +## RELATED LINKS + +[Add-VMHostAssignableDevice](add-vmhostassignabledevice.md) + +[Get-VMHostAssignableDevice](get-vmhostassignabledevice.md) + +[Dismount-VMHostAssignableDevice](dismount-vmhostassignabledevice.md) + +[Remove-VMHostAssignableDevice](remove-vmhostassignabledevice.md) diff --git a/docset/winserver2022-ps/hyper-v/Remove-VMAssignableDevice.md b/docset/winserver2022-ps/hyper-v/Remove-VMAssignableDevice.md new file mode 100644 index 0000000000..66ec201bb8 --- /dev/null +++ b/docset/winserver2022-ps/hyper-v/Remove-VMAssignableDevice.md @@ -0,0 +1,244 @@ +--- +description: Removes a device assigned to a virtual machine. +external help file: Microsoft.HyperV.PowerShell.Cmdlets.dll-Help.xml +Module Name: Hyper-V +ms.date: 06/12/2024 +online version: https://learn.microsoft.com/powershell/module/hyper-v/remove-vmassignabledevice?view=windowsserver2022-ps&wt.mc_id=ps-gethelp +schema: 2.0.0 +title: Remove-VMAssignableDevice +--- + +# Remove-VMAssignableDevice + +## SYNOPSIS +Removes information about the assignable devices from a specific virtual machine. + +## SYNTAX + +### VMName (Default) + +``` +Remove-VMAssignableDevice [-CimSession ] [-ComputerName ] + [-Credential ] [-VMName] [-InstancePath ] + [-LocationPath ] [-Passthru] [-WhatIf] [-Confirm] [] +``` + +### Object + +``` +Remove-VMAssignableDevice [-VMAssignableDevice] [-Passthru] [-WhatIf] + [-Confirm] [] +``` + +## DESCRIPTION + +The `Remove-VMAssignableDevice` cmdlet removes an assignable device from a specified virtual +machine (VM). This is often used in scenarios where a physical device, such as a GPU or network +adapter, was previously assigned to a VM and needs to be unassigned. + +## EXAMPLES + +### Example 1 + +```powershell +$params = @{ +VMName = "MyVM" +InstancePath = "PCIROOT(0)#PCI(0300)#PCI(0000)#PCI(0800)#PCI(0000)#PCI(1000)" +} +Remove-VMAssignableDevice $params +``` + +This example removes a specific assignable device, identified by its instance path, from the +virtual machine named **MyVM**. + +## PARAMETERS + +### -CimSession + +Runs the cmdlet in a remote session or on a remote computer. Enter a computer name or a session +object, such as the output of a [New-CimSession](/powershell/module/cimcmdlets/new-cimsession) +or [Get-CimSession](/powershell/module/cimcmdlets/get-cimsession) cmdlet. The default is the +current session on the local computer. + +```yaml +Type: CimSession[] +Parameter Sets: VMName +Aliases: + +Required: False +Position: Named +Default value: None +Accept pipeline input: False +Accept wildcard characters: False +``` + +### -ComputerName + +Specifies one or more Hyper-V hosts on the virtual network adapters are to be retrieved. NetBIOS +names, IP addresses, and fully qualified domain names are allowed. The default is the local +computer. Use localhost or a dot (`.`) to specify the local computer explicitly. + +```yaml +Type: String[] +Parameter Sets: VMName +Aliases: + +Required: False +Position: Named +Default value: None +Accept pipeline input: False +Accept wildcard characters: False +``` + +### -Credential + +Specifies one or more user accounts that have permission to perform this action. The default is the +current user. + +```yaml +Type: PSCredential[] +Parameter Sets: VMName +Aliases: + +Required: False +Position: Named +Default value: None +Accept pipeline input: False +Accept wildcard characters: False +``` + +### -InstancePath + +Removes the Device Instance path in the host machine. + +```yaml +Type: String +Parameter Sets: VMName +Aliases: + +Required: False +Position: Named +Default value: None +Accept pipeline input: False +Accept wildcard characters: False +``` + +### -LocationPath + +Specifies the location path to the assignable device. + +```yaml +Type: String +Parameter Sets: VMName +Aliases: + +Required: False +Position: Named +Default value: None +Accept pipeline input: False +Accept wildcard characters: False +``` + +### -Passthru + +Returns an object for each process that the cmdlet started. + +```yaml +Type: SwitchParameter +Parameter Sets: (All) +Aliases: + +Required: False +Position: Named +Default value: None +Accept pipeline input: False +Accept wildcard characters: False +``` + +### -VMAssignableDevice + +Specifies the assignable device object that you want to remove from the virtual machine. This is +usually an object retrieved from a cmdlet like `Get-VMAssignableDevice`. + +```yaml +Type: VMAssignedDevice[] +Parameter Sets: Object +Aliases: + +Required: True +Position: 0 +Default value: None +Accept pipeline input: True (ByValue) +Accept wildcard characters: False +``` + +### -VMName + +Specifies the name of the virtual machine from which you want to remove the assignable device. + +```yaml +Type: String[] +Parameter Sets: VMName +Aliases: + +Required: True +Position: 0 +Default value: None +Accept pipeline input: False +Accept wildcard characters: False +``` + +### -Confirm + +Prompts you for confirmation before running the cmdlet. + +```yaml +Type: SwitchParameter +Parameter Sets: (All) +Aliases: cf + +Required: False +Position: Named +Default value: None +Accept pipeline input: False +Accept wildcard characters: False +``` + +### -WhatIf + +Shows what would happen if the cmdlet runs. The cmdlet is not run. + +```yaml +Type: SwitchParameter +Parameter Sets: (All) +Aliases: wi + +Required: False +Position: Named +Default value: None +Accept pipeline input: False +Accept wildcard characters: False +``` + +### CommonParameters + +This cmdlet supports the common parameters: -Debug, -ErrorAction, -ErrorVariable, +-InformationAction, -InformationVariable, -OutVariable, -OutBuffer, -PipelineVariable, -Verbose, +-WarningAction, and -WarningVariable. For more information, see +[about_CommonParameters](/powershell/module/microsoft.powershell.core/about/about_commonparameters). + +## INPUTS + +### Microsoft.HyperV.PowerShell.VMAssignedDevice[] + +## OUTPUTS + +### Microsoft.HyperV.PowerShell.VMAssignedDevice + +## NOTES + +## RELATED LINKS + +[Add-VMAssignableDevice](add-vmassignabledevice.md) + +[Get-VMAssignableDevice](get-vmassignabledevice.md) diff --git a/docset/winserver2022-ps/hyper-v/Remove-VMGpuPartitionAdapter.md b/docset/winserver2022-ps/hyper-v/Remove-VMGpuPartitionAdapter.md index 0815ce1194..c56b987873 100644 --- a/docset/winserver2022-ps/hyper-v/Remove-VMGpuPartitionAdapter.md +++ b/docset/winserver2022-ps/hyper-v/Remove-VMGpuPartitionAdapter.md @@ -2,7 +2,7 @@ description: Removes an assigned GPU partition from a virtual machine. external help file: Microsoft.HyperV.PowerShell.Cmdlets.dll-Help.xml Module Name: Hyper-V -ms.date: 09/22/2022 +ms.date: 06/12/2024 online version: https://learn.microsoft.com/powershell/module/hyper-v/remove-vmgpupartitionadapter?view=windowsserver2022-ps&wt.mc_id=ps-gethelp schema: 2.0.0 title: Remove-VMGpuPartitionAdapter @@ -16,30 +16,36 @@ Removes an assigned GPU partition from a virtual machine. ## SYNTAX ### VMName (Default) + ``` Remove-VMGpuPartitionAdapter [-CimSession ] [-ComputerName ] - [-Credential ] [-VMName] [-Passthru] [-AdapterId ] [-WhatIf] [-Confirm] - [] + [-Credential ] [-VMName] [-Passthru] [-AdapterId ] [-WhatIf] + [-Confirm] [] ``` ### VMObject + ``` -Remove-VMGpuPartitionAdapter [-VM] [-Passthru] [-AdapterId ] [-WhatIf] [-Confirm] - [] +Remove-VMGpuPartitionAdapter [-VM] [-Passthru] [-AdapterId ] [-WhatIf] + [-Confirm] [] ``` ### Object + ``` -Remove-VMGpuPartitionAdapter [-VMGpuPartitionAdapter] [-Passthru] [-WhatIf] - [-Confirm] [] +Remove-VMGpuPartitionAdapter [-VMGpuPartitionAdapter] [-Passthru] + [-WhatIf] [-Confirm] [] ``` ## DESCRIPTION -The 'Remove-VMGpuPartitionAdapter' cmdlet removes an assigned graphic processing unit partition from a virtual machine and releases that partition back to the host GPU. + +The `Remove-VMGpuPartitionAdapter` cmdlet removes an assigned graphic processing unit partition from +a virtual machine and releases that partition back to the host GPU. ## EXAMPLES ### Example 1 + ```powershell $testvm = Get-VM "TestVM" Remove-VMGpuPartitionAdapter -VM $testvm @@ -48,6 +54,7 @@ Remove-VMGpuPartitionAdapter -VM $testvm This example removes a partition assigned to a specific VM object. ### Example 2 + ```powershell $testvm = Get-VM "TestVM" $GPUpartition = Get-VMGpuPartitionAdapter -VM $testvm @@ -59,7 +66,8 @@ This example removes a specific partition object from a specific VM. ## PARAMETERS ### -AdapterId -This is a VM's GPU partition identification number used to remove a GPU from a VM. + +This is a VM's GPU partition identification number used to remove a GPU from a VM. ```yaml Type: String @@ -74,9 +82,11 @@ Accept wildcard characters: False ``` ### -CimSession -Runs the cmdlet in a remote session or on a remote computer. -Enter a computer name or a session object, such as the output of a [New-CimSession](https://go.microsoft.com/fwlink/p/?LinkId=227967) or [Get-CimSession](https://go.microsoft.com/fwlink/p/?LinkId=227966) cmdlet. -The default is the current session on the local computer. + +Runs the cmdlet in a remote session or on a remote computer. Enter a computer name or a session +object, such as the output of a [New-CimSession](/powershell/module/cimcmdlets/new-cimsession) +or [Get-CimSession](/powershell/module/cimcmdlets/get-cimsession) cmdlet. The default is the +current session on the local computer. ```yaml Type: CimSession[] @@ -91,8 +101,10 @@ Accept wildcard characters: False ``` ### -ComputerName -Specifies one or more Hyper-V hosts on the virtual network adapters are to be retrieved. NetBIOS names, IP addresses, and fully qualified domain names are allowed. -The default is the local computer.Use localhost or a dot ('.') to specify the local computer explicitly. + +Specifies one or more Hyper-V hosts on the virtual network adapters are to be retrieved. NetBIOS +names, IP addresses, and fully qualified domain names are allowed. The default is the local +computer.Use localhost or a dot (`.`) to specify the local computer explicitly. ```yaml Type: String[] @@ -107,7 +119,9 @@ Accept wildcard characters: False ``` ### -Credential -Specifies one or more user accounts that have permission to perform this action. The default is the current user. + +Specifies one or more user accounts that have permission to perform this action. The default is the +current user. ```yaml Type: PSCredential[] @@ -122,6 +136,7 @@ Accept wildcard characters: False ``` ### -Passthru + Returns an object for each process that the cmdlet started. ```yaml @@ -137,6 +152,7 @@ Accept wildcard characters: False ``` ### -VM + Specifies the virtual machine whose virtual network adapters are to be retrieved. The asterisk (`*`) is the wildcard. If it is specified the cmdlet returns virtual network adapters from every virtual machine in the system. @@ -154,7 +170,8 @@ Accept wildcard characters: False ``` ### -VMGpuPartitionAdapter -GPU partition object obtained from 'Get-VMGpuPartitionAdapter'. + +GPU partition object obtained from `Get-VMGpuPartitionAdapter`. ```yaml Type: VMGpuPartitionAdapter[] @@ -169,6 +186,7 @@ Accept wildcard characters: False ``` ### -VMName + Specifies the name of the virtual machine whose network adapters are to be retrieved. ```yaml @@ -184,6 +202,7 @@ Accept wildcard characters: False ``` ### -Confirm + Prompts you for confirmation before running the cmdlet. ```yaml @@ -199,8 +218,8 @@ Accept wildcard characters: False ``` ### -WhatIf -Shows what would happen if the cmdlet runs. -The cmdlet is not run. + +Shows what would happen if the cmdlet runs. The cmdlet is not run. ```yaml Type: SwitchParameter @@ -215,7 +234,11 @@ Accept wildcard characters: False ``` ### CommonParameters -This cmdlet supports the common parameters: -Debug, -ErrorAction, -ErrorVariable, -InformationAction, -InformationVariable, -OutVariable, -OutBuffer, -PipelineVariable, -Verbose, -WarningAction, and -WarningVariable. For more information, see [about_CommonParameters](https://go.microsoft.com/fwlink/?LinkID=113216). + +This cmdlet supports the common parameters: -Debug, -ErrorAction, -ErrorVariable, +-InformationAction, -InformationVariable, -OutVariable, -OutBuffer, -PipelineVariable, -Verbose, +-WarningAction, and -WarningVariable. For more information, see +[about_CommonParameters](/powershell/module/microsoft.powershell.core/about/about_commonparameters). ## INPUTS @@ -230,3 +253,9 @@ This cmdlet supports the common parameters: -Debug, -ErrorAction, -ErrorVariable ## NOTES ## RELATED LINKS + +[Add-VMGpuPartitionAdapter](add-vmgpupartitionadapter.md) + +[Get-VMGpuPartitionAdapter](get-vmgpupartitionadapter.md) + +[Set-VMGpuPartitionAdapter](set-vmgpupartitionadapter.md) diff --git a/docset/winserver2022-ps/hyper-v/Remove-VMHostAssignableDevice.md b/docset/winserver2022-ps/hyper-v/Remove-VMHostAssignableDevice.md new file mode 100644 index 0000000000..fa796cc38e --- /dev/null +++ b/docset/winserver2022-ps/hyper-v/Remove-VMHostAssignableDevice.md @@ -0,0 +1,248 @@ +--- +description: Removes an assignable device from a virtual machine host. +external help file: Microsoft.HyperV.PowerShell.Cmdlets.dll-Help.xml +Module Name: Hyper-V +ms.date: 06/12/2024 +online version: https://learn.microsoft.com/powershell/module/hyper-v/remove-vmhostassignabledevice?view=windowsserver2022-ps&wt.mc_id=ps-gethelp +schema: 2.0.0 +title: Remove-VMHostAssignableDevice +--- + +# Remove-VMHostAssignableDevice + +## SYNOPSIS +Removes a device assigned to a virtual machine (VM) host. + +## SYNTAX + +### Path (Default) + +``` +Remove-VMHostAssignableDevice [-CimSession ] [-ComputerName ] + [-Credential ] [-InstancePath ] [-LocationPath ] + -ResourcePoolName [-Force] [-WhatIf] [-Confirm] [] +``` + +### Object + +``` +Remove-VMHostAssignableDevice [-HostAssignableDevice] + -ResourcePoolName [-Force] [-WhatIf] [-Confirm] [] +``` + +## DESCRIPTION + +The `Remove-VMHostAssignableDevice` cmdlet removes a device that is assigned to a virtual machine +host. Depending on the parameters specified, you can remove devices by providing either the +instance or location path of the device. + +## EXAMPLES + +### Example 1 + +```powershell +$params = @{ +InstancePath = "PCIROOT(0)#PCI(0300)#PCI(0000)" +ResourcePoolName = "MyResourcePool" +} +Remove-VMHostAssignableDevice $params +``` + +This example removes the device with the specified instance path from the resource pool named +**MyResourcePool**. + +## PARAMETERS + +### -CimSession + +Runs the cmdlet in a remote session or on a remote computer. Enter a computer name or a session +object, such as the output of a [New-CimSession](/powershell/module/cimcmdlets/new-cimsession) +or [Get-CimSession](/powershell/module/cimcmdlets/get-cimsession) cmdlet. The default is the +current session on the local computer. + +```yaml +Type: CimSession[] +Parameter Sets: Path +Aliases: + +Required: False +Position: Named +Default value: None +Accept pipeline input: False +Accept wildcard characters: False +``` + +### -ComputerName + +Specifies one or more Hyper-V hosts from which the assignable devices are to be removed. NetBIOS +names, IP addresses, and fully qualified domain names are allowed. The default is the local +computer. Use localhost or a dot (`.`) to specify the local computer explicitly. + +```yaml +Type: String[] +Parameter Sets: Path +Aliases: + +Required: False +Position: Named +Default value: None +Accept pipeline input: False +Accept wildcard characters: False +``` + +### -Credential + +Specifies one or more user accounts that have permission to perform this action. The default is the +current user. + +```yaml +Type: PSCredential[] +Parameter Sets: Path +Aliases: + +Required: False +Position: Named +Default value: None +Accept pipeline input: False +Accept wildcard characters: False +``` + +### -Force + +Forces the command to run without asking for user confirmation. + +```yaml +Type: SwitchParameter +Parameter Sets: (All) +Aliases: + +Required: False +Position: Named +Default value: None +Accept pipeline input: False +Accept wildcard characters: False +``` + +### -HostAssignableDevice + +Specifies the device object to be removed. You can get this object using +`Get-VMHostAssignableDevice`. + +```yaml +Type: VMHostAssignableDevice[] +Parameter Sets: Object +Aliases: VMHostAssignableDevice + +Required: True +Position: 0 +Default value: None +Accept pipeline input: True (ByValue) +Accept wildcard characters: False +``` + +### -InstancePath + +Specifies the Device Instance path in the host machine. + +```yaml +Type: String +Parameter Sets: Path +Aliases: + +Required: False +Position: Named +Default value: None +Accept pipeline input: False +Accept wildcard characters: False +``` + +### -LocationPath + +Specifies the location path to the assignable device. + +```yaml +Type: String +Parameter Sets: Path +Aliases: + +Required: False +Position: Named +Default value: None +Accept pipeline input: False +Accept wildcard characters: False +``` + +### -ResourcePoolName + +Specifies the name of the resource pool from which to remove an assignable device. + +```yaml +Type: String[] +Parameter Sets: (All) +Aliases: + +Required: True +Position: Named +Default value: None +Accept pipeline input: False +Accept wildcard characters: False +``` + +### -Confirm + +Prompts you for confirmation before running the cmdlet. + +```yaml +Type: SwitchParameter +Parameter Sets: (All) +Aliases: cf + +Required: False +Position: Named +Default value: None +Accept pipeline input: False +Accept wildcard characters: False +``` + +### -WhatIf + +Shows what would happen if the cmdlet runs. The cmdlet is not run. + +```yaml +Type: SwitchParameter +Parameter Sets: (All) +Aliases: wi + +Required: False +Position: Named +Default value: None +Accept pipeline input: False +Accept wildcard characters: False +``` + +### CommonParameters + +This cmdlet supports the common parameters: -Debug, -ErrorAction, -ErrorVariable, +-InformationAction, -InformationVariable, -OutVariable, -OutBuffer, -PipelineVariable, -Verbose, +-WarningAction, and -WarningVariable. For more information, see +[about_CommonParameters](/powershell/module/microsoft.powershell.core/about/about_commonparameters). + +## INPUTS + +### Microsoft.HyperV.PowerShell.VMHostAssignableDevice[] + +## OUTPUTS + +### System.Object + +## NOTES + +## RELATED LINKS + +[Add-VMHostAssignableDevice](add-vmhostassignabledevice.md) + +[Get-VMHostAssignableDevice](get-vmhostassignabledevice.md) + +[Dismount-VMHostAssignableDevice](dismount-vmhostassignabledevice.md) + +[Mount-VMHostAssignableDevice](mount-vmhostassignabledevice.md) diff --git a/docset/winserver2022-ps/hyper-v/Set-VMGpuPartitionAdapter.md b/docset/winserver2022-ps/hyper-v/Set-VMGpuPartitionAdapter.md index e6311979a5..cbbc027a4e 100644 --- a/docset/winserver2022-ps/hyper-v/Set-VMGpuPartitionAdapter.md +++ b/docset/winserver2022-ps/hyper-v/Set-VMGpuPartitionAdapter.md @@ -2,7 +2,7 @@ description: Assigns a partition of a GPU to a virtual machine. external help file: Microsoft.HyperV.PowerShell.Cmdlets.dll-Help.xml Module Name: Hyper-V -ms.date: 09/22/2022 +ms.date: 06/12/2024 online version: https://learn.microsoft.com/powershell/module/hyper-v/set-vmgpupartitionadapter?view=windowsserver2022-ps&wt.mc_id=ps-gethelp schema: 2.0.0 title: Set-VMGpuPartitionAdapter @@ -16,44 +16,51 @@ Assigns a partition of a GPU to a virtual machine. ## SYNTAX ### VMName (Default) + ``` Set-VMGpuPartitionAdapter [-CimSession ] [-ComputerName ] [-Credential ] [-VMName] [-Passthru] [-AdapterId ] [-MinPartitionVRAM ] [-MaxPartitionVRAM ] [-OptimalPartitionVRAM ] [-MinPartitionEncode ] [-MaxPartitionEncode ] [-OptimalPartitionEncode ] [-MinPartitionDecode ] [-MaxPartitionDecode ] [-OptimalPartitionDecode ] - [-MinPartitionCompute ] [-MaxPartitionCompute ] [-OptimalPartitionCompute ] [-WhatIf] - [-Confirm] [] + [-MinPartitionCompute ] [-MaxPartitionCompute ] [-OptimalPartitionCompute ] + [-WhatIf] [-Confirm] [] ``` ### VMObject + ``` Set-VMGpuPartitionAdapter [-VM] [-Passthru] [-AdapterId ] [-MinPartitionVRAM ] [-MaxPartitionVRAM ] [-OptimalPartitionVRAM ] [-MinPartitionEncode ] [-MaxPartitionEncode ] [-OptimalPartitionEncode ] [-MinPartitionDecode ] [-MaxPartitionDecode ] [-OptimalPartitionDecode ] - [-MinPartitionCompute ] [-MaxPartitionCompute ] [-OptimalPartitionCompute ] [-WhatIf] - [-Confirm] [] + [-MinPartitionCompute ] [-MaxPartitionCompute ] [-OptimalPartitionCompute ] + [-WhatIf] [-Confirm] [] ``` ### Object + ``` Set-VMGpuPartitionAdapter [-VMGpuPartitionAdapter] [-Passthru] [-MinPartitionVRAM ] [-MaxPartitionVRAM ] [-OptimalPartitionVRAM ] [-MinPartitionEncode ] [-MaxPartitionEncode ] [-OptimalPartitionEncode ] [-MinPartitionDecode ] [-MaxPartitionDecode ] [-OptimalPartitionDecode ] - [-MinPartitionCompute ] [-MaxPartitionCompute ] [-OptimalPartitionCompute ] [-WhatIf] - [-Confirm] [] + [-MinPartitionCompute ] [-MaxPartitionCompute ] [-OptimalPartitionCompute ] + [-WhatIf] [-Confirm] [] ``` ## DESCRIPTION -The 'Set-VMGpuPartitionAdapter' cmdlet assigns a partition of a GPU to a virtual machine. Running the command against a virtual machine assigns a full partition. Additional parameters exist to assign more specific options to a VM. + +The `Set-VMGpuPartitionAdapter` cmdlet assigns a partition of a GPU to a virtual machine. Running +the command against a virtual machine assigns a full partition. Additional parameters exist to +assign more specific options to a VM. ## EXAMPLES ### Example 1 + ```powershell -$vm = get-vm test +$vm = Get-VM "Test" Set-VMGpuPartitionAdapter -VM $vm ``` @@ -62,6 +69,7 @@ This example assign a partition to a VM passing a VM object. ## PARAMETERS ### -AdapterId + A VM's GPU partition identification number used to display the GPU information assigned to a VM. ```yaml @@ -77,8 +85,11 @@ Accept wildcard characters: False ``` ### -CimSession -Runs the cmdlet in a remote session or on a remote computer. Enter a computer name or a session object, such as the output of a [New-CimSession](https://go.microsoft.com/fwlink/p/?LinkId=227967) or [Get-CimSession](https://go.microsoft.com/fwlink/p/?LinkId=227966) cmdlet. -The default is the current session on the local computer. + +Runs the cmdlet in a remote session or on a remote computer. Enter a computer name or a session +object, such as the output of a [New-CimSession](/powershell/module/cimcmdlets/new-cimsession) +or [Get-CimSession](/powershell/module/cimcmdlets/get-cimsession) cmdlet. The default is the +current session on the local computer. ```yaml Type: CimSession[] @@ -93,9 +104,10 @@ Accept wildcard characters: False ``` ### -ComputerName -Specifies one or more Hyper-V hosts on the virtual network adapters are to be retrieved. NetBIOS names, IP addresses, and fully qualified domain names are allowed. -The default is the local computer. -Use localhost or a dot ('.') to specify the local computer explicitly. + +Specifies one or more Hyper-V hosts on the virtual network adapters are to be retrieved. NetBIOS +names, IP addresses, and fully qualified domain names are allowed. The default is the local +computer. Use localhost or a dot (`.`) to specify the local computer explicitly. ```yaml Type: String[] @@ -110,8 +122,9 @@ Accept wildcard characters: False ``` ### -Credential -Specifies one or more user accounts that have permission to perform this action. -The default is the current user. + +Specifies one or more user accounts that have permission to perform this action. The default is the +current user. ```yaml Type: PSCredential[] @@ -126,7 +139,9 @@ Accept wildcard characters: False ``` ### -MaxPartitionCompute -The maximum number of compute assigned by the host GPU. This is defined by the manufacturer's driver. + +The maximum number of compute assigned by the host GPU. This is defined by the manufacturer's +driver. ```yaml Type: UInt64 @@ -141,7 +156,9 @@ Accept wildcard characters: False ``` ### -MaxPartitionDecode -The maximum number of decoders assigned by the host GPU. This is defined by the manufacturer's driver. + +The maximum number of decoders assigned by the host GPU. This is defined by the manufacturer's +driver. ```yaml Type: UInt64 @@ -156,7 +173,9 @@ Accept wildcard characters: False ``` ### -MaxPartitionEncode -The maximum number of encoders assigned by the host GPU. This is defined by the manufacturer's driver. + +The maximum number of encoders assigned by the host GPU. This is defined by the manufacturer's +driver. ```yaml Type: UInt64 @@ -171,6 +190,7 @@ Accept wildcard characters: False ``` ### -MaxPartitionVRAM + The maximum VRAM in bytes supported by the host GPU. This is defined by the manufacturer's driver. ```yaml @@ -186,7 +206,9 @@ Accept wildcard characters: False ``` ### -MinPartitionCompute -The minimum number of compute assigned by the host GPU. This is defined by the manufacturer's driver. + +The minimum number of compute assigned by the host GPU. This is defined by the manufacturer's +driver. ```yaml Type: UInt64 @@ -201,7 +223,9 @@ Accept wildcard characters: False ``` ### -MinPartitionDecode -The minimum number of decoders assigned by the host GPU. This is defined by the manufacturer's driver. + +The minimum number of decoders assigned by the host GPU. This is defined by the manufacturer's +driver. ```yaml Type: UInt64 @@ -216,7 +240,9 @@ Accept wildcard characters: False ``` ### -MinPartitionEncode -The minimum number of encoders assigned by the host GPU. This is defined by the manufacturer's driver. + +The minimum number of encoders assigned by the host GPU. This is defined by the manufacturer's +driver. ```yaml Type: UInt64 @@ -231,6 +257,7 @@ Accept wildcard characters: False ``` ### -MinPartitionVRAM + The minimum VRAM in bytes supported by the host GPU. This is defined by the manufacturer's driver. ```yaml @@ -246,7 +273,9 @@ Accept wildcard characters: False ``` ### -OptimalPartitionCompute -The optimal number of compute assigned by the host GPU. This is defined by the manufacturer's driver. + +The optimal number of compute assigned by the host GPU. This is defined by the manufacturer's +driver. ```yaml Type: UInt64 @@ -261,7 +290,9 @@ Accept wildcard characters: False ``` ### -OptimalPartitionDecode -The optimal number of decoders assigned by the host GPU. This is defined by the manufacturer's driver. + +The optimal number of decoders assigned by the host GPU. This is defined by the manufacturer's +driver. ```yaml Type: UInt64 @@ -276,7 +307,9 @@ Accept wildcard characters: False ``` ### -OptimalPartitionEncode -The optimal number of encoders assigned by the host GPU. This is defined by the manufacturer's driver. + +The optimal number of encoders assigned by the host GPU. This is defined by the manufacturer's +driver. ```yaml Type: UInt64 @@ -291,6 +324,7 @@ Accept wildcard characters: False ``` ### -OptimalPartitionVRAM + The optimal VRAM in bytes supported by the host GPU. This is defined by the manufacturer's driver. ```yaml @@ -306,6 +340,7 @@ Accept wildcard characters: False ``` ### -Passthru + Returns an object for each process that the cmdlet started. ```yaml @@ -321,6 +356,7 @@ Accept wildcard characters: False ``` ### -VM + Specifies the virtual machine whose virtual network adapters are to be retrieved. The asterisk (`*`) is the wildcard. If it is specified the cmdlet returns virtual network adapters from every virtual machine in the system. @@ -338,7 +374,8 @@ Accept wildcard characters: False ``` ### -VMGpuPartitionAdapter -GPU partition object obtained from 'Get-VMGpuPartitionAdapter'. + +GPU partition object obtained from `Get-VMGpuPartitionAdapter`. ```yaml Type: VMGpuPartitionAdapter[] @@ -353,6 +390,7 @@ Accept wildcard characters: False ``` ### -VMName + Specifies the name of the virtual machine whose network adapters are to be retrieved. ```yaml @@ -368,6 +406,7 @@ Accept wildcard characters: False ``` ### -Confirm + Prompts you for confirmation before running the cmdlet. ```yaml @@ -383,8 +422,8 @@ Accept wildcard characters: False ``` ### -WhatIf -Shows what would happen if the cmdlet runs. -The cmdlet is not run. + +Shows what would happen if the cmdlet runs. The cmdlet is not run. ```yaml Type: SwitchParameter @@ -399,7 +438,11 @@ Accept wildcard characters: False ``` ### CommonParameters -This cmdlet supports the common parameters: -Debug, -ErrorAction, -ErrorVariable, -InformationAction, -InformationVariable, -OutVariable, -OutBuffer, -PipelineVariable, -Verbose, -WarningAction, and -WarningVariable. For more information, see [about_CommonParameters](https://go.microsoft.com/fwlink/?LinkID=113216). + +This cmdlet supports the common parameters: -Debug, -ErrorAction, -ErrorVariable, +-InformationAction, -InformationVariable, -OutVariable, -OutBuffer, -PipelineVariable, -Verbose, +-WarningAction, and -WarningVariable. For more information, see +[about_CommonParameters](/powershell/module/microsoft.powershell.core/about/about_commonparameters). ## INPUTS @@ -416,3 +459,9 @@ This cmdlet supports the common parameters: -Debug, -ErrorAction, -ErrorVariable ## NOTES ## RELATED LINKS + +[Add-VMGpuPartitionAdapter](add-vmgpupartitionadapter.md) + +[Get-VMGpuPartitionAdapter](get-vmgpupartitionadapter.md) + +[Remove-VMGpuPartitionAdapter](remove-vmgpupartitionadapter.md) diff --git a/docset/winserver2022-ps/hyper-v/Set-VMHostPartitionableGpu.md b/docset/winserver2022-ps/hyper-v/Set-VMHostPartitionableGpu.md index 6cca814585..3a2bf70ec7 100644 --- a/docset/winserver2022-ps/hyper-v/Set-VMHostPartitionableGpu.md +++ b/docset/winserver2022-ps/hyper-v/Set-VMHostPartitionableGpu.md @@ -2,7 +2,7 @@ description: Configures the host partitionable GPU to the number of partitions supported by the manufacturer. external help file: Microsoft.HyperV.PowerShell.Cmdlets.dll-Help.xml Module Name: Hyper-V -ms.date: 10/21/2022 +ms.date: 06/12/2024 online version: https://learn.microsoft.com/powershell/module/hyper-v/set-vmhostpartitionablegpu?view=windowsserver2022-ps&wt.mc_id=ps-gethelp schema: 2.0.0 title: Set-VMHostPartitionableGpu @@ -16,44 +16,51 @@ Configures the host partitionable GPU to the number of partitions supported by t ## SYNTAX ### ComputerName (Default) + ``` Set-VMHostPartitionableGpu [[-ComputerName] ] [[-Credential] ] [-Passthru] [-PartitionCount ] [] ``` ### CimSession + ``` Set-VMHostPartitionableGpu [-CimSession] [-Passthru] [-PartitionCount ] [] ``` ### Object + ``` Set-VMHostPartitionableGpu [-HostPartitionableGpu] [-Passthru] [-PartitionCount ] [] ``` ### Name + ``` Set-VMHostPartitionableGpu [-Passthru] [-Name ] [-PartitionCount ] [] ``` ## DESCRIPTION + The `Set-VMHostPartitionableGpu` cmdlet configures the host partitionable GPU to the number of partitions supported by the manufacturer. ## EXAMPLES ### Example 1 + ```powershell -Set-VMHostPartitionableGpu -ComputerName SampleHost -partitioncount 8 +Set-VMHostPartitionableGpu -ComputerName "MyHost" -PartitionCount 8 ``` This example partitions a GPU in a specific host into eight partitions. ### Example 2 + ```powershell -$GPU = Get-VMHostPartitionableGpu -name "SampleGPUDeviceIDName" -Set-VMHostPartitionableGpu -Name $GPU -partitionCount 4 +$GPU = Get-VMHostPartitionableGpu -Name "GPUDeviceIDName" +Set-VMHostPartitionableGpu -Name $GPU -PartitionCount 4 ``` This example partitions a GPU in a host into four partitions by using the GPU device ID name. @@ -61,8 +68,11 @@ This example partitions a GPU in a host into four partitions by using the GPU de ## PARAMETERS ### -CimSession -Runs the cmdlet in a remote session or on a remote computer. Enter a computer name or a session object, such as the output of a [New-CimSession](https://go.microsoft.com/fwlink/p/?LinkId=227967) or [Get-CimSession](https://go.microsoft.com/fwlink/p/?LinkId=227966) cmdlet. -The default is the current session on the local computer. + +Runs the cmdlet in a remote session or on a remote computer. Enter a computer name or a session +object, such as the output of a [New-CimSession](/powershell/module/cimcmdlets/new-cimsession) +or [Get-CimSession](/powershell/module/cimcmdlets/get-cimsession) cmdlet. The default is the +current session on the local computer. ```yaml Type: CimSession[] @@ -77,9 +87,10 @@ Accept wildcard characters: False ``` ### -ComputerName -Specifies one or more Hyper-V hosts on the virtual network adapters are to be retrieved. NetBIOS names, IP addresses, and fully qualified domain names are allowed. -The default is the local computer. -Use localhost or a dot ('.') to specify the local computer explicitly. + +Specifies one or more Hyper-V hosts on the virtual network adapters are to be retrieved. NetBIOS +names, IP addresses, and fully qualified domain names are allowed. The default is the local +computer. Use localhost or a dot (`.`) to specify the local computer explicitly. ```yaml Type: String[] @@ -94,8 +105,9 @@ Accept wildcard characters: False ``` ### -Credential -Specifies one or more user accounts that have permission to perform this action. -The default is the current user. + +Specifies one or more user accounts that have permission to perform this action. The default is the +current user. ```yaml Type: PSCredential[] @@ -110,7 +122,8 @@ Accept wildcard characters: False ``` ### -HostPartitionableGpu -Full GPU object, obtained by executing 'Get-VMHostPartitionableGpu'. + +Full GPU object, obtained by executing `Get-VMHostPartitionableGpu`. ```yaml Type: VMHostPartitionableGpu[] @@ -125,6 +138,7 @@ Accept wildcard characters: False ``` ### -Name + Specifies the name of the GPU. ```yaml @@ -140,7 +154,9 @@ Accept wildcard characters: False ``` ### -PartitionCount -Specifies the number of partitions that the GPU will assign. The number of partitions is defined by the manufacturer. + +Specifies the number of partitions that the GPU will assign. The number of partitions is defined by +the manufacturer. ```yaml Type: UInt16 @@ -155,6 +171,7 @@ Accept wildcard characters: False ``` ### -Passthru + Returns an object for each process that the cmdlet started. ```yaml @@ -170,7 +187,11 @@ Accept wildcard characters: False ``` ### CommonParameters -This cmdlet supports the common parameters: -Debug, -ErrorAction, -ErrorVariable, -InformationAction, -InformationVariable, -OutVariable, -OutBuffer, -PipelineVariable, -Verbose, -WarningAction, and -WarningVariable. For more information, see [about_CommonParameters](https://go.microsoft.com/fwlink/?LinkID=113216). + +This cmdlet supports the common parameters: -Debug, -ErrorAction, -ErrorVariable, +-InformationAction, -InformationVariable, -OutVariable, -OutBuffer, -PipelineVariable, -Verbose, +-WarningAction, and -WarningVariable. For more information, see +[about_CommonParameters](/powershell/module/microsoft.powershell.core/about/about_commonparameters). ## INPUTS @@ -185,3 +206,5 @@ This cmdlet supports the common parameters: -Debug, -ErrorAction, -ErrorVariable ## NOTES ## RELATED LINKS + +[Get-VMHostPartitionableGpu](get-vmhostpartitionablegpu.md) diff --git a/docset/winserver2022-ps/smbshare/Block-SmbClientAccessToServer.md b/docset/winserver2022-ps/smbshare/Block-SmbClientAccessToServer.md new file mode 100644 index 0000000000..26191aee75 --- /dev/null +++ b/docset/winserver2022-ps/smbshare/Block-SmbClientAccessToServer.md @@ -0,0 +1,289 @@ +--- +description: Use this topic to help manage Windows and Windows Server technologies with Windows PowerShell. +external help file: SmbClientAccessToServer.cdxml-help.xml +Module Name: SmbShare +ms.date: 02/22/2024 +online version: https://learn.microsoft.com/powershell/module/smbshare/block-smbclientaccesstoserver?view=windowsserver2022-ps&wt.mc_id=ps-gethelp +schema: 2.0.0 +title: Block-SmbClientAccessToServer +--- + +# Block-SmbClientAccessToServer + +## SYNOPSIS +Blocks SMB client access to a specified server. + +## SYNTAX + +### Query + +``` +Block-SmbClientAccessToServer [-Name] -IdentifierType + -Identifier [-Description ] [-Force] [-CimSession ] + [-ThrottleLimit ] [-AsJob] [-WhatIf] [-Confirm] [] +``` + +### InputObject + +``` +Block-SmbClientAccessToServer -InputObject -IdentifierType + -Identifier [-Description ] [-Force] [-CimSession ] + [-ThrottleLimit ] [-AsJob] [-WhatIf] [-Confirm] [] +``` + +## DESCRIPTION + +The `Block-SmbClientAccessToServer` cmdlet is used to prevent SMB clients from accessing a +specified server when using SMB over QUIC client access control. When you run this cmdlet, all SMB +client connections to the specified server will be terminated, and no new connections will be +allowed until the block is lifted. To unblock access to the server, use the +`Unblock-SmbClientAccessToServer` cmdlet. + +## EXAMPLES + +### Example 1: Block SMB client access to a server + +```powershell +$params = @{ + Name = "Server01" + IdentifierType = "ISSUER" + Identifier = "CN=MyCertificateIssuer" + Force = $true +} +Block-SmbClientAccessToServer @params +``` + +This command blocks SMB client access to a server named `Server01` for the based on the client's +certificate. This command runs without prompting for confirmation as the **Force** parameter is set +to `$true`. + +## PARAMETERS + +### -AsJob + +Runs the cmdlet as a background job. Use this parameter to run commands that take a long time to +complete. + +```yaml +Type: SwitchParameter +Parameter Sets: (All) +Aliases: + +Required: False +Position: Named +Default value: None +Accept pipeline input: False +Accept wildcard characters: False +``` + +### -CimSession + +Runs the cmdlet in a remote session or on a remote computer. Enter a computer name or a session +object, such as the output of a [New-CimSession](/powershell/module/cimcmdlets/new-cimsession) or +[Get-CimSession](/powershell/module/cimcmdlets/get-cimsession) cmdlet. The default is the +current session on the local computer. + +```yaml +Type: CimSession[] +Parameter Sets: (All) +Aliases: Session + +Required: False +Position: Named +Default value: None +Accept pipeline input: False +Accept wildcard characters: False +``` + +### -Description + +Used to provide a description of the rule being added to the server's firewall when you use the +`Block-SmbClientAccessToServer` cmdlet. This can be useful if you need to keep track of why SMB +client access to a server has been blocked, or if you need to provide additional information about +the block for documentation purposes. + +```yaml +Type: String +Parameter Sets: (All) +Aliases: + +Required: False +Position: Named +Default value: None +Accept pipeline input: False +Accept wildcard characters: False +``` + +### -Force + +Forces the command to run without asking for user confirmation. + +```yaml +Type: SwitchParameter +Parameter Sets: (All) +Aliases: + +Required: False +Position: Named +Default value: None +Accept pipeline input: False +Accept wildcard characters: False +``` + +### -Identifier + +Specifies the identity of the client that is being granted access to the SMB server. This parameter +takes a string value that represents the identity of the client. The format of the string value +will depend on the **IdentifierType** parameter that you're using. + +```yaml +Type: String +Parameter Sets: (All) +Aliases: + +Required: True +Position: Named +Default value: None +Accept pipeline input: False +Accept wildcard characters: False +``` + +### -IdentifierType + +Specifies the type of identifier that you're using to identify a client. The valid values for the +**IdentifierType** parameter are: + +- SHA256 +- ISSUER + +If you're using the `SHA256` identifier type, you're specifying a hash value that uniquely +identifies the client. If you're using the `ISSUER` identifier type, you're specifying the issuer +of the client's certificate. + +```yaml +Type: IdentifierType +Parameter Sets: (All) +Aliases: +Accepted values: SHA256, ISSUER + +Required: True +Position: Named +Default value: None +Accept pipeline input: False +Accept wildcard characters: False +``` + +### -InputObject + +Specifies the input object that's used in a pipeline command. + +```yaml +Type: CimInstance[] +Parameter Sets: InputObject +Aliases: + +Required: True +Position: Named +Default value: None +Accept pipeline input: True (ByValue) +Accept wildcard characters: False +``` + +### -Name + +Specifies a fully-qualified DNS name or NetBIOS name that must match the certificate's subject name +or an entry in the certificate's subject alternative names. + +```yaml +Type: String[] +Parameter Sets: Query +Aliases: + +Required: True +Position: 1 +Default value: None +Accept pipeline input: True (ByPropertyName) +Accept wildcard characters: False +``` + +### -ThrottleLimit + +Specifies the maximum number of concurrent operations that can be established to run the cmdlet. If +this parameter is omitted or a value of `0` is entered, then Windows PowerShell calculates an +optimum throttle limit for the cmdlet based on the number of CIM cmdlets that are running on the +computer. + +The throttle limit applies only to the current cmdlet, not to the session or to the computer. + +```yaml +Type: Int32 +Parameter Sets: (All) +Aliases: + +Required: False +Position: Named +Default value: None +Accept pipeline input: False +Accept wildcard characters: False +``` + +### -Confirm + +Prompts you for confirmation before running the cmdlet. + +```yaml +Type: SwitchParameter +Parameter Sets: (All) +Aliases: cf + +Required: False +Position: Named +Default value: False +Accept pipeline input: False +Accept wildcard characters: False +``` + +### -WhatIf + +Shows what would happen if the cmdlet runs. The cmdlet isn't run. + +```yaml +Type: SwitchParameter +Parameter Sets: (All) +Aliases: wi + +Required: False +Position: Named +Default value: False +Accept pipeline input: False +Accept wildcard characters: False +``` + +### CommonParameters + +This cmdlet supports the common parameters: -Debug, -ErrorAction, -ErrorVariable, +-InformationAction, -InformationVariable, -OutVariable, -OutBuffer, -PipelineVariable, -Verbose, +-WarningAction, and -WarningVariable. For more information, see +[about_CommonParameters](/powershell/module/microsoft.powershell.core/about/about_commonparameters). + +## INPUTS + +### System.String[] + +### Microsoft.Management.Infrastructure.CimInstance[] + +## OUTPUTS + +### Microsoft.Management.Infrastructure.CimInstance[] + +## NOTES + +## RELATED LINKS + +[Get-SmbClientAccessToServer](Get-SmbClientAccessToServer.md) + +[Grant-SmbClientAccessToServer](Grant-SmbClientAccessToServer.md) + +[Revoke-SmbClientAccessToServer](Revoke-SmbClientAccessToServer.md) + +[Unblock-SmbClientAccessToServer](Unblock-SmbClientAccessToServer.md) diff --git a/docset/winserver2022-ps/smbshare/Get-SmbClientAccessToServer.md b/docset/winserver2022-ps/smbshare/Get-SmbClientAccessToServer.md new file mode 100644 index 0000000000..d840f0e478 --- /dev/null +++ b/docset/winserver2022-ps/smbshare/Get-SmbClientAccessToServer.md @@ -0,0 +1,199 @@ +--- +description: Use this topic to help manage Windows and Windows Server technologies with Windows PowerShell. +external help file: SmbClientAccessToServer.cdxml-help.xml +Module Name: SmbShare +ms.date: 02/22/2024 +online version: https://learn.microsoft.com/powershell/module/smbshare/get-smbclientaccesstoserver?view=windowsserver2022-ps&wt.mc_id=ps-gethelp +schema: 2.0.0 +title: Get-SmbClientAccessToServer +--- + +# Get-SmbClientAccessToServer + +## SYNOPSIS +Gets information about SMB client access to a specified server. + +## SYNTAX + +### Query + +``` +Get-SmbClientAccessToServer [-Name] [-CimSession ] [-ThrottleLimit ] + [-AsJob] [-WhatIf] [-Confirm] [] +``` + +### InputObject + +``` +Get-SmbClientAccessToServer -InputObject [-CimSession ] + [-ThrottleLimit ] [-AsJob] [-WhatIf] [-Confirm] [] +``` + +## DESCRIPTION + +The `Get-SmbClientAccessToServer` cmdlet is used to retrieve information about SMB client access to +a specified server. When you run this cmdlet, it'll return a list of allowed and blocked +connections for SMB over QUIC client access control. + +## EXAMPLES + +### Example 1: Retrieve client access information + +```powershell +Get-SmbClientAccessToServer -Name "Server01" +``` + +This command retrieves the SMB client access information for a device named `Server01`. + +## PARAMETERS + +### -AsJob + +Runs the cmdlet as a background job. Use this parameter to run commands that take a long time to +complete. + +```yaml +Type: SwitchParameter +Parameter Sets: (All) +Aliases: + +Required: False +Position: Named +Default value: None +Accept pipeline input: False +Accept wildcard characters: False +``` + +### -CimSession + +Runs the cmdlet in a remote session or on a remote computer. Enter a computer name or a session +object, such as the output of a [New-CimSession](/powershell/module/cimcmdlets/new-cimsession) or +[Get-CimSession](/powershell/module/cimcmdlets/get-cimsession) cmdlet. The default is the +current session on the local computer. + +```yaml +Type: CimSession[] +Parameter Sets: (All) +Aliases: Session + +Required: False +Position: Named +Default value: None +Accept pipeline input: False +Accept wildcard characters: False +``` + +### -InputObject + +Specifies the input object that's used in a pipeline command. + +```yaml +Type: CimInstance[] +Parameter Sets: InputObject +Aliases: + +Required: True +Position: Named +Default value: None +Accept pipeline input: True (ByValue) +Accept wildcard characters: False +``` + +### -Name + +Specifies a fully-qualified DNS name or NetBIOS name that must match the certificate's subject name +or an entry in the certificate's subject alternative names. + +```yaml +Type: String[] +Parameter Sets: Query +Aliases: + +Required: True +Position: 1 +Default value: None +Accept pipeline input: True (ByPropertyName) +Accept wildcard characters: False +``` + +### -ThrottleLimit + +Specifies the maximum number of concurrent operations that can be established to run the cmdlet. If +this parameter is omitted or a value of `0` is entered, then Windows PowerShell calculates an +optimum throttle limit for the cmdlet based on the number of CIM cmdlets that are running on the +computer. + +The throttle limit applies only to the current cmdlet, not to the session or to the computer. + +```yaml +Type: Int32 +Parameter Sets: (All) +Aliases: + +Required: False +Position: Named +Default value: None +Accept pipeline input: False +Accept wildcard characters: False +``` + +### -Confirm + +Prompts you for confirmation before running the cmdlet. + +```yaml +Type: SwitchParameter +Parameter Sets: (All) +Aliases: cf + +Required: False +Position: Named +Default value: False +Accept pipeline input: False +Accept wildcard characters: False +``` + +### -WhatIf + +Shows what would happen if the cmdlet runs. The cmdlet isn't run. + +```yaml +Type: SwitchParameter +Parameter Sets: (All) +Aliases: wi + +Required: False +Position: Named +Default value: False +Accept pipeline input: False +Accept wildcard characters: False +``` + +### CommonParameters + +This cmdlet supports the common parameters: -Debug, -ErrorAction, -ErrorVariable, +-InformationAction, -InformationVariable, -OutVariable, -OutBuffer, -PipelineVariable, -Verbose, +-WarningAction, and -WarningVariable. For more information, see +[about_CommonParameters](/powershell/module/microsoft.powershell.core/about/about_commonparameters). + +## INPUTS + +### System.String[] + +### Microsoft.Management.Infrastructure.CimInstance[] + +## OUTPUTS + +### Microsoft.Management.Infrastructure.CimInstance[] + +## NOTES + +## RELATED LINKS + +[Block-SmbClientAccessToServer](Block-SmbClientAccessToServer.md) + +[Grant-SmbClientAccessToServer](Grant-SmbClientAccessToServer.md) + +[Revoke-SmbClientAccessToServer](Revoke-SmbClientAccessToServer.md) + +[Unblock-SmbClientAccessToServer](Unblock-SmbClientAccessToServer.md) diff --git a/docset/winserver2022-ps/smbshare/Get-SmbClientCertificateMapping.md b/docset/winserver2022-ps/smbshare/Get-SmbClientCertificateMapping.md new file mode 100644 index 0000000000..ff46c3fa70 --- /dev/null +++ b/docset/winserver2022-ps/smbshare/Get-SmbClientCertificateMapping.md @@ -0,0 +1,291 @@ +--- +description: Use this topic to help manage Windows and Windows Server technologies with Windows PowerShell. +external help file: SmbClientCertificateMapping.cdxml-help.xml +Module Name: SmbShare +ms.date: 02/22/2024 +online version: https://learn.microsoft.com/powershell/module/smbshare/get-smbclientcertificatemapping?view=windowsserver2022-ps&wt.mc_id=ps-gethelp +schema: 2.0.0 +title: Get-SmbClientCertificateMapping +--- + +# Get-SmbClientCertificateMapping + +## SYNOPSIS +Retrieves the client certificate mappings for the Server Message Block (SMB) protocol. + +## SYNTAX + +``` +Get-SmbClientCertificateMapping [[-Namespace] ] [[-Subject] ] + [-IssuerName ] [-Thumbprint ] [-DisplayName ] [-StoreName ] + [-Type ] [-Flags ] [-IncludeHidden] [-CimSession ] + [-ThrottleLimit ] [-AsJob] [] +``` + +## DESCRIPTION + +The `Get-SmbClientCertificateMapping` cmdlet retrieves the client certificate mappings for the SMB +protocol, such as when using SMB over QUIC. These mappings are used to authenticate clients that +connect to SMB servers using certificates. + +## EXAMPLES + +### Example 1: Retrieve all certificate mappings for a specific store + +```powershell +Get-SmbClientCertificateMapping -StoreName "My" +``` + +This retrieves all certificate mappings that have been stored in a specific certificate store. + +### Example 2: Retrieve a specific certificate mapping by display name + +```powershell +Get-SmbClientCertificateMapping -DisplayName "MyCertificateMapping" +``` + +This retrieves a specific certificate mapping by its display name. + +## PARAMETERS + +### -AsJob + +Runs the cmdlet as a background job. Use this parameter to run commands that take a long time to +complete. + +```yaml +Type: SwitchParameter +Parameter Sets: (All) +Aliases: + +Required: False +Position: Named +Default value: None +Accept pipeline input: False +Accept wildcard characters: False +``` + +### -CimSession + +Runs the cmdlet in a remote session or on a remote computer. Enter a computer name or a session +object, such as the output of a [New-CimSession](/powershell/module/cimcmdlets/new-cimsession) +or [Get-CimSession](/powershell/module/cimcmdlets/get-cimsession) cmdlet. The default is the +current session on the local computer. + +```yaml +Type: CimSession[] +Parameter Sets: (All) +Aliases: Session + +Required: False +Position: Named +Default value: None +Accept pipeline input: False +Accept wildcard characters: False +``` + +### -DisplayName + +Specifies the friendly name of the certificate. + +```yaml +Type: String[] +Parameter Sets: (All) +Aliases: + +Required: False +Position: Named +Default value: None +Accept pipeline input: True (ByPropertyName) +Accept wildcard characters: False +``` + +### -Flags + +Specifies if `NamedPipes` are enabled for SMB over QUIC. The acceptable values for this parameter +are: + +- `None`: Remove all flags +- `AllowNamedPipe`: Enable use of named pipes in SMB over QUIC connections for this mapping (off by + default, overrides value of the **RestrictNamedPipeAccessOverQuic** parameter) +- `DefaultCert`: Not used + +```yaml +Type: Flags[] +Parameter Sets: (All) +Aliases: +Accepted values: None, AllowNamedPipe, DefaultCert + +Required: False +Position: Named +Default value: None +Accept pipeline input: True (ByPropertyName) +Accept wildcard characters: False +``` + +### -IncludeHidden + +Not used. + +```yaml +Type: SwitchParameter +Parameter Sets: (All) +Aliases: + +Required: False +Position: Named +Default value: None +Accept pipeline input: False +Accept wildcard characters: False +``` + +### -IssuerName + +Filters the certificate mappings based on the issuer name of the certificate. + +```yaml +Type: String[] +Parameter Sets: (All) +Aliases: + +Required: False +Position: Named +Default value: None +Accept pipeline input: True (ByPropertyName) +Accept wildcard characters: False +``` + +### -Namespace + +Specifies the namespace in which the certificate mappings are located. By default, the cmdlet +searches in the `root\cimv2\Security\MicrosoftTlsCertificateMappingProvider` namespace. + +```yaml +Type: String[] +Parameter Sets: (All) +Aliases: + +Required: False +Position: 1 +Default value: None +Accept pipeline input: True (ByPropertyName) +Accept wildcard characters: False +``` + +### -StoreName + +Specifies the path to the certificate store for the certificate. + +```yaml +Type: String[] +Parameter Sets: (All) +Aliases: + +Required: False +Position: Named +Default value: None +Accept pipeline input: True (ByPropertyName) +Accept wildcard characters: False +``` + +### -Subject + +Specifies the subject name of the certificate. + +```yaml +Type: String[] +Parameter Sets: (All) +Aliases: + +Required: False +Position: 2 +Default value: None +Accept pipeline input: True (ByPropertyName) +Accept wildcard characters: False +``` + +### -ThrottleLimit + +Specifies the maximum number of concurrent operations that can be established to run the cmdlet. If +this parameter is omitted or a value of `0` is entered, then Windows PowerShell calculates an +optimum throttle limit for the cmdlet based on the number of CIM cmdlets that are running on the +computer. The throttle limit applies only to the current cmdlet, not to the session or to the +computer. + +```yaml +Type: Int32 +Parameter Sets: (All) +Aliases: + +Required: False +Position: Named +Default value: None +Accept pipeline input: False +Accept wildcard characters: False +``` + +### -Thumbprint + +Specifies the thumbprint value of the certificate. + +```yaml +Type: String[] +Parameter Sets: (All) +Aliases: + +Required: False +Position: Named +Default value: None +Accept pipeline input: True (ByPropertyName) +Accept wildcard characters: False +``` + +### -Type + +Specifies the type of certificate mapping. The acceptable value for this parameter is: + +`QUIC`: Certificate mapping is for SMB over QUIC. + +```yaml +Type: Type[] +Parameter Sets: (All) +Aliases: +Accepted values: QUIC + +Required: False +Position: Named +Default value: None +Accept pipeline input: True (ByPropertyName) +Accept wildcard characters: False +``` + +### CommonParameters + +This cmdlet supports the common parameters: -Debug, -ErrorAction, -ErrorVariable, +-InformationAction, -InformationVariable, -OutVariable, -OutBuffer, -PipelineVariable, -Verbose, +-WarningAction, and -WarningVariable. For more information, see +[about_CommonParameters](/powershell/module/microsoft.powershell.core/about/about_commonparameters). + +## INPUTS + +### System.String[] + +### Microsoft.PowerShell.Cmdletization.GeneratedTypes.SmbClientCertificateMapping.Type[] + +### Microsoft.PowerShell.Cmdletization.GeneratedTypes.SmbClientCertificateMapping.Flags[] + +## OUTPUTS + +### Microsoft.Management.Infrastructure.CimInstance + +### Microsoft.Management.Infrastructure.CimInstance#ROOT/Microsoft/Windows/SMB/MSFT_SmbClientCertificateMapping + +## NOTES + +## RELATED LINKS + +[New-SmbClientCertificateMapping](New-SmbClientCertificateMapping.md) + +[Remove-SmbClientCertificateMapping](Remove-SmbClientCertificateMapping.md) + +[Set-SmbClientCertificateMapping](Set-SmbClientCertificateMapping.md) diff --git a/docset/winserver2022-ps/smbshare/Get-SmbServerCertificateMapping.md b/docset/winserver2022-ps/smbshare/Get-SmbServerCertificateMapping.md index 997c4e3d00..5a4e92e961 100644 --- a/docset/winserver2022-ps/smbshare/Get-SmbServerCertificateMapping.md +++ b/docset/winserver2022-ps/smbshare/Get-SmbServerCertificateMapping.md @@ -2,7 +2,7 @@ description: Use this topic to help manage Windows and Windows Server technologies with Windows PowerShell. external help file: SmbServerCertificateMapping.cdxml-help.xml Module Name: SmbShare -ms.date: 08/31/2021 +ms.date: 02/22/2024 online version: https://learn.microsoft.com/powershell/module/smbshare/get-smbservercertificatemapping?view=windowsserver2022-ps&wt.mc_id=ps-gethelp schema: 2.0.0 title: Get-SmbServerCertificateMapping @@ -16,34 +16,55 @@ Retrieves a certificate associated with the SMB server for SMB over QUIC. ## SYNTAX ``` -Get-SmbServerCertificateMapping [[-Name] ] [[-Subject] ] [-Thumbprint ] - [-DisplayName ] [-StoreName ] [-Type ] [-Flags ] [-IncludeHidden] - [-CimSession ] [-ThrottleLimit ] [-AsJob] [] +Get-SmbServerCertificateMapping [[-Name] ] [[-Subject] ] + [-Thumbprint ] [-DisplayName ] [-StoreName ] [-Type ] + [-Flags ] [-RequireClientAuthentication ] + [-SkipClientCertificateAccessCheck ] [-IncludeHidden] [-CimSession ] + [-ThrottleLimit ] [-AsJob] [] ``` ## DESCRIPTION -The **Get-SmbServerCertificateMapping** cmdlet retrieves the certificates associated with the SMB server for SMB over QUIC on ‘Windows Server 2022 Datacenter: Azure Edition’. This cmdlet is not used for Windows or other Windows Server editions. For more information, review [SMB over QUIC](https://aka.ms/smboverquic). + +The `Get-SmbServerCertificateMapping` cmdlet retrieves the certificates associated with the SMB +server for SMB over QUIC. For more information, see [SMB over QUIC](https://aka.ms/smboverquic). + +> [!NOTE] +> +> - The **RequireClientAuthentication** and **SkipClientCertificateAccessCheck** parameters are only +> supported in Windows Server 2022 Datacenter: Azure Edition. +> +> - If the **RequireClientAuthentication** parameter is set to `$true` and +> **SkipClientCertificateAccessCheck** is set to `$false`, the server will perform both client +> certificate validation and access control checks. +> +> - If the **RequireClientAuthentication** parameter is set to `$true` and +> **SkipClientCertificateAccessCheck** is also set to `$true`, the server will perform client +> certificate validation but no access control checks. ## EXAMPLES ### Example 1 - Retrieve the certificate mapped to two SMB over QUIC server names -This command retrieves the certificate mapped to two SMB over QUIC server names that clients can connect to, `fs2.contoso.com` and `2022-ae-02.corp.contoso.com`. +This command retrieves the certificate mapped to two SMB over QUIC server names that clients can +connect to, `fs2.contoso.com` and `2022-ae-02.corp.contoso.com`. ```powershell -PS C:\> Get-SmbServerCertificateMapping +Get-SmbServerCertificateMapping ``` + ```output -Name Subject Thumbprint DisplayName StoreName Type Flags ----- ------- ---------- ----------- --------- ---- ----- -2022-ae-02.corp.contoso.com CN=2022-ae-02 88032B3551FAF7DE26EFFFF814AA086E3DBD2A4F 2022-ae-02 My QUIC None +Name Subject Thumbprint DisplayName StoreName Type Flags +---- ------- ---------- ----------- --------- ---- ----- +2022-ae-02.corp.contoso.com CN=2022-ae-02 88032B3551FAF7DE26EFFFF814AA086E3DBD2A4F 2022-ae-02 My QUIC None fs2.contoso.com CN=2022-ae-02 88032B3551FAF7DE26EFFFF814AA086E3DBD2A4F 2022-ae-02 My QUIC None ``` ## PARAMETERS ### -AsJob -Runs the cmdlet as a background job. Use this parameter to run commands that take a long time to complete. + +Runs the cmdlet as a background job. Use this parameter to run commands that take a long time to +complete. ```yaml Type: SwitchParameter @@ -58,7 +79,11 @@ Accept wildcard characters: False ``` ### -CimSession -Runs the cmdlet in a remote session or on a remote computer. Enter a computer name or a session object, such as the output of a [`New-CimSession`](/powershell/module/cimcmdlets/new-cimsession) or [`Get-CimSession`](https://go.microsoft.com/fwlink/p/?LinkId=227966) cmdlet. The default is the current session on the local computer. + +Runs the cmdlet in a remote session or on a remote computer. Enter a computer name or a session +object, such as the output of a [`New-CimSession`](/powershell/module/cimcmdlets/new-cimsession) or +[`Get-CimSession`](/powershell/module/cimcmdlets/get-cimsession) cmdlet. The default is the +current session on the local computer. ```yaml Type: CimSession[] @@ -73,6 +98,7 @@ Accept wildcard characters: False ``` ### -DisplayName + Specifies a friendly name to display for the mapping. ```yaml @@ -88,12 +114,14 @@ Accept wildcard characters: False ``` ### -Flags -Specifies if `NamedPipes` are enabled for SMB over QUIC. The acceptable values for this parameter are: +Specifies if `NamedPipes` are enabled for SMB over QUIC. The acceptable values for this parameter +are: -- `None:` Remove all flags -- `AllowNamedPipe:` Enable use of named pipes in SMB over QUIC connections for this mapping (off by default, overrides value of RestrictNamedPipeAccessOverQuic) -- `DefaultCert:` Not used +- `None`: Remove all flags +- `AllowNamedPipe`: Enable use of named pipes in SMB over QUIC connections for this mapping (off by + default, overrides value of the **RestrictNamedpipeAccessOverQuic** parameter) +- `DefaultCert`: Not used ```yaml Type: Flags[] @@ -109,6 +137,7 @@ Accept wildcard characters: False ``` ### -IncludeHidden + Not used. ```yaml @@ -124,7 +153,9 @@ Accept wildcard characters: False ``` ### -Name -Specifies a fully-qualified DNS name or NetBIOS name that must match the certificate’s subject name or an entry in the certificate’s subject alternative names. + +Specifies a fully-qualified DNS name or NetBIOS name that must match the certificate's subject name +or an entry in the certificate's subject alternative names. ```yaml Type: String[] @@ -138,7 +169,51 @@ Accept pipeline input: True (ByPropertyName) Accept wildcard characters: False ``` +### -RequireClientAuthentication + +Specifies whether client authentication is required for connections to the server. When this +parameter is set to `$true`, clients must present a valid certificate to connect to the server. +When it is set to `$false`, clients can connect without presenting a certificate. + +```yaml +Type: Boolean[] +Parameter Sets: (All) +Aliases: + +Required: False +Position: Named +Default value: None +Accept pipeline input: True (ByPropertyName) +Accept wildcard characters: False +``` + +### -SkipClientCertificateAccessCheck + +Specifies whether the server should skip the check for client certificate access when a client +connects. This parameter only applies when the server certificate mapping +**RequireClientAuthentication** value is `$true`. When this parameter is set to `$true`, the server +will not perform the access control checks based on the client certificates. This can be useful in +scenarios where the server is acting as a gateway or proxy and client certificate validation is +sufficient. + +However, it can also increase the risk of security breaches. When this parameter is set to +`$false`, the server will perform the access control checks based on the client certificates in +addition to the client certificate validation before allowing the client to connect. + +```yaml +Type: Boolean[] +Parameter Sets: (All) +Aliases: + +Required: False +Position: Named +Default value: None +Accept pipeline input: True (ByPropertyName) +Accept wildcard characters: False +``` + ### -StoreName + Specifies the path to the certificate store for the certificate. ```yaml @@ -154,6 +229,7 @@ Accept wildcard characters: False ``` ### -Subject + Specifies the subject name of the certificate. ```yaml @@ -169,7 +245,12 @@ Accept wildcard characters: False ``` ### -ThrottleLimit -Specifies the maximum number of concurrent operations that can be established to run the cmdlet. If this parameter is omitted or a value of 0 is entered, then Windows PowerShell calculates an optimum throttle limit for the cmdlet based on the number of CIM cmdlets that are running on the computer. The throttle limit applies only to the current cmdlet, not to the session or to the computer. + +Specifies the maximum number of concurrent operations that can be established to run the cmdlet. If +this parameter is omitted or a value of `0` is entered, then Windows PowerShell calculates an +optimum throttle limit for the cmdlet based on the number of CIM cmdlets that are running on the +computer. The throttle limit applies only to the current cmdlet, not to the session or to the +computer. ```yaml Type: Int32 @@ -184,6 +265,7 @@ Accept wildcard characters: False ``` ### -Thumbprint + Specifies the thumbprint value of the certificate. ```yaml @@ -199,9 +281,10 @@ Accept wildcard characters: False ``` ### -Type -Specifies the type of certificate mapping. The acceptable value for this parameter is: -`QUIC:` Certificate mapping is for SMB over QUIC. +Specifies the type of certificate mapping. The acceptable value for this parameter is: + +- `QUIC`: Certificate mapping is for SMB over QUIC. ```yaml Type: Type[] @@ -217,7 +300,11 @@ Accept wildcard characters: False ``` ### CommonParameters -This cmdlet supports the common parameters: -Debug, -ErrorAction, -ErrorVariable, -InformationAction, -InformationVariable, -OutVariable, -OutBuffer, -PipelineVariable, -Verbose, -WarningAction, and -WarningVariable. For more information, see [about_CommonParameters](https://go.microsoft.com/fwlink/?LinkID=113216). + +This cmdlet supports the common parameters: -Debug, -ErrorAction, -ErrorVariable, +-InformationAction, -InformationVariable, -OutVariable, -OutBuffer, -PipelineVariable, -Verbose, +-WarningAction, and -WarningVariable. For more information, see +[about_CommonParameters](/powershell/module/microsoft.powershell.core/about/about_commonparameters). ## INPUTS @@ -227,6 +314,8 @@ This cmdlet supports the common parameters: -Debug, -ErrorAction, -ErrorVariable ### Microsoft.PowerShell.Cmdletization.GeneratedTypes.SmbServerCertificateMapping.Flags[] +### System.Boolean[] + ## OUTPUTS ### Microsoft.Management.Infrastructure.CimInstance @@ -236,3 +325,9 @@ This cmdlet supports the common parameters: -Debug, -ErrorAction, -ErrorVariable ## NOTES ## RELATED LINKS + +[New-SmbServerCertificateMapping](New-SmbServerCertificateMapping.md) + +[Remove-SmbServerCertificateMapping](Remove-SmbServerCertificateMapping.md) + +[Set-SmbServerCertificateMapping](Set-SmbServerCertificateMapping.md) diff --git a/docset/winserver2022-ps/smbshare/Get-SmbServerConfiguration.md b/docset/winserver2022-ps/smbshare/Get-SmbServerConfiguration.md index f030032ce0..e114010dce 100644 --- a/docset/winserver2022-ps/smbshare/Get-SmbServerConfiguration.md +++ b/docset/winserver2022-ps/smbshare/Get-SmbServerConfiguration.md @@ -2,7 +2,7 @@ description: Use this topic to help manage Windows and Windows Server technologies with Windows PowerShell. external help file: SmbServerConfiguration.cdxml-help.xml Module Name: SmbShare -ms.date: 06/23/2022 +ms.date: 02/22/2024 online version: https://learn.microsoft.com/powershell/module/smbshare/get-smbserverconfiguration?view=windowsserver2022-ps&wt.mc_id=ps-gethelp schema: 2.0.0 title: Get-SmbServerConfiguration @@ -22,7 +22,8 @@ Get-SmbServerConfiguration [-CimSession ] [-ThrottleLimit ] ## DESCRIPTION -The `Get-SmbServerConfiguration` cmdlet retrieves the Server Message Block (SMB) server configuration. +The `Get-SmbServerConfiguration` cmdlet retrieves the Server Message Block (SMB) server +configuration. ## EXAMPLES @@ -32,15 +33,17 @@ The `Get-SmbServerConfiguration` cmdlet retrieves the Server Message Block (SMB) Get-SmbServerConfiguration ``` -```Output -AnnounceComment : +```output +AnnounceComment : AnnounceServer : False AsynchronousCredits : 512 +AuditClientCertificateAccess : False AuditSmb1Access : False AutoDisconnectTimeout : 15 AutoShareServer : True AutoShareWorkstation : True CachedOpenLimit : 10 +DisableCompression : False DisableSmbEncryptionOnSecureConnection : True DurableHandleV2TimeoutInSeconds : 180 EnableAuthenticateUserSharing : False @@ -52,8 +55,10 @@ EnableOplocks : True EnableSecuritySignature : False EnableSMB1Protocol : False EnableSMB2Protocol : True +EnableSMBQUIC : True EnableStrictNameChecking : True EncryptData : False +EncryptionCiphers : AES_128_GCM, AES_128_CCM, AES_256_GCM, AES_256_CCM IrpStackSize : 15 KeepAliveTime : 2 MaxChannelPerSession : 32 @@ -61,12 +66,14 @@ MaxMpxCount : 50 MaxSessionPerConnection : 16384 MaxThreadsPerQueue : 20 MaxWorkItems : 1 -NullSessionPipes : -NullSessionShares : +NullSessionPipes : +NullSessionShares : OplockBreakWait : 35 PendingClientTimeoutInSeconds : 120 RejectUnencryptedAccess : True +RequestCompression : False RequireSecuritySignature : False +RestrictNamedpipeAccessViaQuic : True ServerHidden : True Smb2CreditsMax : 8192 Smb2CreditsMin : 512 @@ -76,19 +83,10 @@ ValidateAliasNotCircular : True ValidateShareScope : True ValidateShareScopeNotAliased : True ValidateTargetName : True -RestrictNamedpipeAccessViaQuic : True -EnableSMBQUIC : True -EncryptionCiphers : AES_128_GCM, AES_128_CCM, AES_256_GCM, AES_256_CCM ``` This command retrieves the SMB server configuration. -> [!NOTE] -> The **EncryptionCiphers** parameter is available beginning with 2022-06 Cumulative Update for -> Microsoft server operating system version 21H2 for x64-based Systems -> ([KB5014665](https://support.microsoft.com/help/5014665)), and Cumulative Update for Windows 11, -> version 22H2 ([KB5014668](https://support.microsoft.com/help/5014668)). - ## PARAMETERS ### -AsJob @@ -111,8 +109,8 @@ Accept wildcard characters: False ### -CimSession Runs the cmdlet in a remote session or on a remote computer. Enter a computer name or a session -object, such as the output of a [New-CimSession](https://go.microsoft.com/fwlink/p/?LinkId=227967) -or [Get-CimSession](https://go.microsoft.com/fwlink/p/?LinkId=227966) cmdlet. The default is the +object, such as the output of a [New-CimSession](/powershell/module/cimcmdlets/new-cimsession) +or [Get-CimSession](/powershell/module/cimcmdlets/get-cimsession) cmdlet. The default is the current session on the local computer. ```yaml @@ -158,15 +156,14 @@ Aliases: cf Required: False Position: Named -Default value: False +Default value: None Accept pipeline input: False Accept wildcard characters: False ``` ### -WhatIf -Shows what would happen if the cmdlet runs. -The cmdlet is not run. +Shows what would happen if the cmdlet runs. The cmdlet isn't run. ```yaml Type: SwitchParameter @@ -185,7 +182,7 @@ Accept wildcard characters: False This cmdlet supports the common parameters: -Debug, -ErrorAction, -ErrorVariable, -InformationAction, -InformationVariable, -OutVariable, -OutBuffer, -PipelineVariable, -Verbose, -WarningAction, and -WarningVariable. For more information, see -[about_CommonParameters](https://go.microsoft.com/fwlink/?LinkID=113216). +[about_CommonParameters](/powershell/module/microsoft.powershell.core/about/about_commonparameters). ## INPUTS @@ -201,4 +198,6 @@ The **MSFT_SmbServerConfiguration** object represents the configuration of the S ## RELATED LINKS -[Set-SmbServerConfiguration](./Set-SmbServerConfiguration.md) +[Reset-SmbServerConfiguration](Reset-SmbServerConfiguration.md) + +[Set-SmbServerConfiguration](Set-SmbServerConfiguration.md) diff --git a/docset/winserver2022-ps/smbshare/Get-SmbShare.md b/docset/winserver2022-ps/smbshare/Get-SmbShare.md index a5f4a87637..34bf76bd90 100644 --- a/docset/winserver2022-ps/smbshare/Get-SmbShare.md +++ b/docset/winserver2022-ps/smbshare/Get-SmbShare.md @@ -26,116 +26,127 @@ Get-SmbShare [[-Name] ] [[-ScopeName] ] [-Scoped ``` ## DESCRIPTION -The **Get-SmbShare** cmdlet retrieves objects that represent the Server Message Block (SMB) shares being displayed by the computer. + +The `Get-SmbShare` cmdlet retrieves objects that represent the Server Message Block (SMB) shares +being displayed by the computer. ## EXAMPLES ### Example 1: Get SMB shares on a local computer -``` -PS C:\>Get-SMBShare -Name ScopeName Path Description ----- --------- ---- ----------- -ADMIN$ * C:\Windows Remote Admin -C$ * C:\ Default share -D$ * D:\ Default share -F$ * F:\ Default share -IPC$ * Remote IPC + +```powershell +Get-SMBShare +Name ScopeName Path Description +---- --------- ---- ----------- +ADMIN$ * C:\\Windows Remote Admin +C$ * C:\\ Default share +D$ * D:\\ Default share +F$ * F:\ Default share +IPC$ * Remote IPC VMS1 * I:\VMS ``` This command retrieves the SMB shares on the computer. ### Example 2: Get a specific SMB share on the local computer -``` -PS C:\>Get-SmbShare -Name "VMS1" -Name ScopeName Path Description ----- --------- ---- ----------- + +```powershell +Get-SmbShare -Name "VMS1" +Name ScopeName Path Description +---- --------- ---- ----------- VMS1 * I:\VMS ``` -This command retrieves information about the SMB share named 'VMS1' on the local computer. +This command retrieves information about the SMB share named `VMS1` on the local computer. ### Example 3: Display information about the SMB shares on a remote computer -``` -PS C:\>get-smbshare -CimSession "NEDFS1" + +```powershell +Get-SmbShare -CimSession "NEDFS1" Name ScopeName Path Description PSComputerName ---- --------- ---- ----------- -------------- -ADMIN$ * C:\Windows Remote Admin ae-dfsr-sr-01 -C$ * C:\ Default share ae-dfsr-sr-01 -D$ * D:\ Default share ae-dfsr-sr-01 -E$ * E:\ Default share ae-dfsr-sr-01 -IPC$ * Remote IPC ae-dfsr-sr-01 -IT dept * D:\data\IT dept ae-dfsr-sr-01 -procedures * D:\hr\procedures ae-dfsr-sr-01 -VHD and ISO * D:\data\VHD and ISO ae-dfsr-sr-01 - +ADMIN$ * C:\\Windows Remote Admin ae-dfsr-sr-01 +C$ * C:\\ Default share ae-dfsr-sr-01 +D$ * D:\\ Default share ae-dfsr-sr-01 +E$ * E:\\ Default share ae-dfsr-sr-01 +IPC$ * Remote IPC ae-dfsr-sr-01 +IT dept * D:\\data\IT dept ae-dfsr-sr-01 +procedures * D:\\hr\procedures ae-dfsr-sr-01 +VHD and ISO * D:\\data\VHD and ISO ae-dfsr-sr-01 ``` -This command displays the information about the SMB shares on the remote computer NEDFS1. +This command displays the information about the SMB shares on the remote computer `NEDFS1`. ### Example 4: Display all properties about a specific SMB share on the local computer in a list -``` -PS C:\>Get-SmbShare -Name "VMS1" | Format-List -Property * -PresetPathAcl : System.Security.AccessControl.DirectorySecurity -ShareState : Online -AvailabilityType : Clustered -ShareType : FileSystemDirectory -FolderEnumerationMode : Unrestricted -CachingMode : Manual -CATimeout : 0 -ConcurrentUserLimit : 0 -ContinuouslyAvailable : True -CurrentUsers : 3 -Description : -EncryptData : False -Name : VMS1 -Path : I:\VMS -Scoped : True + +```powershell +Get-SmbShare -Name "VMS1" | Format-List -Property * +PresetPathAcl : System.Security.AccessControl.DirectorySecurity +ShareState : Online +AvailabilityType : Clustered +ShareType : FileSystemDirectory +FolderEnumerationMode : Unrestricted +CachingMode : Manual +CATimeout : 0 +ConcurrentUserLimit : 0 +ContinuouslyAvailable : True +CurrentUsers : 3 +Description : +EncryptData : False +Name : VMS1 +Path : I:\VMS +Scoped : True ScopeName : * -SecurityDescriptor : O:BAG:DUD:(A;;FA;;;S-1-5-21-219828122-4198910963-4161819395-500)(A;;FA;;;S-1-5-21-219828122-419 - 8910963-4161819395-1106)(A;;FA;;;S-1-5-21-219828122-4198910963-4161819395-1109) -ShadowCopy : False -Special : False -Temporary : False -Volume : \\?\Volume{b02c4ba7-e6f1-11e1-93eb-0008a1c0ef0d}\ -PSComputerName : -CimClass : ROOT/Microsoft/Windows/SMB:MSFT_SmbShare -CimInstanceProperties : {AvailabilityType, CachingMode, CATimeout, ConcurrentUserLimit...} +SecurityDescriptor : O:BAG:DUD:(A;;FA;;;S-1-5-21-219828122-4198910963-4161819395-500)(A;;FA;;;S-1-5-21-219828122-419 + 8910963-4161819395-1106)(A;;FA;;;S-1-5-21-219828122-4198910963-4161819395-1109) +ShadowCopy : False +Special : False +Temporary : False +Volume : \\?\Volume{b02c4ba7-e6f1-11e1-93eb-0008a1c0ef0d}\ +PSComputerName : +CimClass : ROOT/Microsoft/Windows/SMB:MSFT_SmbShare +CimInstanceProperties : {AvailabilityType, CachingMode, CATimeout, ConcurrentUserLimit...} CimSystemProperties : Microsoft.Management.Infrastructure.CimSystemProperties ``` -This command displays all of the information about the SMB share named 'VMS1' on the local computer as a formatted list. +This command displays all of the information about the SMB share named `VMS1` on the local computer +as a formatted list. ### Example 5: Get shares on the local failover cluster computer that have scale out availability -``` -PS C:\>Get-SmbShare | Where-Object -Property AvailabilityType -Eq ScaleOut -Name ScopeName Path Description ----- --------- ---- ----------- -ClusterStorage$ Contoso-SO C:\ClusterStorage Cluster Shared Volumes Def... -VMS3 Contoso-SO C:\ClusterStorage\Volume1\VMS -VMS4 Contoso-SO C:\ClusterStorage\Volume2\VMS + +```powershell +Get-SmbShare | Where-Object -Property AvailabilityType -Eq ScaleOut +Name ScopeName Path Description +---- --------- ---- ----------- +ClusterStorage$ Contoso-SO C:\\ClusterStorage Cluster Shared Volumes Def... +VMS3 Contoso-SO C:\\ClusterStorage\Volume1\VMS +VMS4 Contoso-SO C:\\ClusterStorage\Volume2\VMS ``` This command retrieves the SMB shares on the computer that have scaled out availability. ### Example 6: Get shares that are connected to a local failover cluster file server resource named "Contoso-FS" -``` -PS C:\>Get-SmbShare -ScopeName "Contoso-FS" -Name ScopeName Path Description ----- --------- ---- ----------- -I$ Contoso-FS I:\ Cluster Default Share -J$ Contoso-FS J:\ Cluster Default Share -VMS1 Contoso-FS I:\VMS + +```powershell +Get-SmbShare -ScopeName "Contoso-FS" +Name ScopeName Path Description +---- --------- ---- ----------- +I$ Contoso-FS I:\ Cluster Default Share +J$ Contoso-FS J:\ Cluster Default Share +VMS1 Contoso-FS I:\VMS VMS2 Contoso-FS J:\VMS ``` -This command retrieves the SMB shares on the Windows Server failover cluster that are connected to the clustered file server resource named Contoso-FS. +This command retrieves the SMB shares on the Windows Server failover cluster that are connected to +the clustered file server resource named `Contoso-FS`. ## PARAMETERS ### -AsJob -Runs the cmdlet as a background job. Use this parameter to run commands that take a long time to complete. + +Runs the cmdlet as a background job. Use this parameter to run commands that take a long time to +complete. ```yaml Type: SwitchParameter @@ -150,6 +161,7 @@ Accept wildcard characters: False ``` ### -AvailabilityType + Specifies the cluster type of the shares being enumerated. ```yaml @@ -166,6 +178,7 @@ Accept wildcard characters: False ``` ### -CaTimeout + Specifies the continuous availability time-out of the shares being enumerated. ```yaml @@ -181,6 +194,7 @@ Accept wildcard characters: False ``` ### -CachingMode + Specifies the caching mode of the shares being enumerated. ```yaml @@ -197,9 +211,11 @@ Accept wildcard characters: False ``` ### -CimSession -Runs the cmdlet in a remote session or on a remote computer. -Enter a computer name or a session object, such as the output of a [New-CimSession](https://go.microsoft.com/fwlink/p/?LinkId=227967) or [Get-CimSession](https://go.microsoft.com/fwlink/p/?LinkId=227966) cmdlet. -The default is the current session on the local computer. + +Runs the cmdlet in a remote session or on a remote computer. Enter a computer name or a session +object, such as the output of a [New-CimSession](/powershell/module/cimcmdlets/new-cimsession) +or [Get-CimSession](/powershell/module/cimcmdlets/get-cimsession) cmdlet. The default is the +current session on the local computer. ```yaml Type: CimSession[] @@ -214,6 +230,7 @@ Accept wildcard characters: False ``` ### -CompressData + Indicates that the shares being enumerated should request compression from clients. ```yaml @@ -229,6 +246,7 @@ Accept wildcard characters: False ``` ### -ConcurrentUserLimit + Specifies the concurrent user limit of the shares being enumerated. ```yaml @@ -244,6 +262,7 @@ Accept wildcard characters: False ``` ### -ContinuouslyAvailable + Indicates that the shares being enumerated should be continuously available. ```yaml @@ -259,6 +278,7 @@ Accept wildcard characters: False ``` ### -EncryptData + Indicates that the shares being enumerated should be encrypted. ```yaml @@ -274,6 +294,7 @@ Accept wildcard characters: False ``` ### -FolderEnumerationMode + Specifies the folder enumeration mode of the shares being enumerated. ```yaml @@ -290,6 +311,7 @@ Accept wildcard characters: False ``` ### -IncludeHidden + Indicates that shares that are created and used internally are also enumerated. ```yaml @@ -305,6 +327,7 @@ Accept wildcard characters: False ``` ### -LeasingMode + Specifies SMB leasing and oplock behaviors. ```yaml @@ -320,6 +343,7 @@ Accept wildcard characters: False ``` ### -Name + Specifies one or more SMB shares by share name. ```yaml @@ -335,7 +359,9 @@ Accept wildcard characters: False ``` ### -ScopeName -Specifies the scope of the share by name. For use with Windows Server failover cluster file server resources. + +Specifies the scope of the share by name. For use with Windows Server failover cluster file server +resources. ```yaml Type: String[] @@ -350,6 +376,7 @@ Accept wildcard characters: False ``` ### -Scoped + Indicates that the shares to be numerated should be scoped. ```yaml @@ -365,6 +392,7 @@ Accept wildcard characters: False ``` ### -ShareState + Specifies the state of the shares being enumerated. ```yaml @@ -381,8 +409,9 @@ Accept wildcard characters: False ``` ### -SmbInstance -Specifies the input to this cmdlet. -You can use this parameter, or you can pipe the input to this cmdlet. + +Specifies the input to this cmdlet. You can use this parameter, or you can pipe the input to this +cmdlet. ```yaml Type: SmbInstance @@ -398,8 +427,9 @@ Accept wildcard characters: False ``` ### -Special -Indicates that the shares to be numerated should be special. -Admin share, default shares, IPC$ share are examples of special shares. + +Indicates that the shares to be numerated should be special. Admin share, default shares, IPC$ +share are examples of special shares. ```yaml Type: Boolean[] @@ -414,9 +444,12 @@ Accept wildcard characters: False ``` ### -ThrottleLimit -Specifies the maximum number of concurrent operations that can be established to run the cmdlet. -If this parameter is omitted or a value of `0` is entered, then Windows PowerShell® calculates an optimum throttle limit for the cmdlet based on the number of CIM cmdlets that are running on the computer. -The throttle limit applies only to the current cmdlet, not to the session or to the computer. + +Specifies the maximum number of concurrent operations that can be established to run the cmdlet. If +this parameter is omitted or a value of `0` is entered, then Windows PowerShell® calculates an +optimum throttle limit for the cmdlet based on the number of CIM cmdlets that are running on the +computer. The throttle limit applies only to the current cmdlet, not to the session or to the +computer. ```yaml Type: Int32 @@ -431,7 +464,11 @@ Accept wildcard characters: False ``` ### CommonParameters -This cmdlet supports the common parameters: -Debug, -ErrorAction, -ErrorVariable, -InformationAction, -InformationVariable, -OutVariable, -OutBuffer, -PipelineVariable, -Verbose, -WarningAction, and -WarningVariable. For more information, see [about_CommonParameters](https://go.microsoft.com/fwlink/?LinkID=113216). + +This cmdlet supports the common parameters: -Debug, -ErrorAction, -ErrorVariable, +-InformationAction, -InformationVariable, -OutVariable, -OutBuffer, -PipelineVariable, -Verbose, +-WarningAction, and -WarningVariable. For more information, see +[about_CommonParameters](/powershell/module/microsoft.powershell.core/about/about_commonparameters). ## INPUTS @@ -440,16 +477,18 @@ This cmdlet supports the common parameters: -Debug, -ErrorAction, -ErrorVariable ## OUTPUTS ### Microsoft.Management.Infrastructure.CimInstance#ROOT/Microsoft/Windows/SMB/MSFT_SmbShare -The `Microsoft.Management.Infrastructure.CimInstance` object is a wrapper class that displays Windows Management Instrumentation (WMI) objects. -The path after the pound sign (`#`) provides the namespace and class name for the underlying WMI object. -The **MSFT_SmbShare** object represents the SMB shares on the computer. + +The `Microsoft.Management.Infrastructure.CimInstance` object is a wrapper class that displays +Windows Management Instrumentation (WMI) objects. The path after the pound sign (`#`) provides the +namespace and class name for the underlying WMI object. The **MSFT_SmbShare** object represents the +SMB shares on the computer. ## NOTES ## RELATED LINKS -[New-SmbShare](./New-SmbShare.md) +[New-SmbShare](New-SmbShare.md) -[Remove-SmbShare](./Remove-SmbShare.md) +[Remove-SmbShare](Remove-SmbShare.md) -[Set-SmbShare](./Set-SmbShare.md) +[Set-SmbShare](Set-SmbShare.md) diff --git a/docset/winserver2022-ps/smbshare/Grant-SmbClientAccessToServer.md b/docset/winserver2022-ps/smbshare/Grant-SmbClientAccessToServer.md new file mode 100644 index 0000000000..70e4a35b8e --- /dev/null +++ b/docset/winserver2022-ps/smbshare/Grant-SmbClientAccessToServer.md @@ -0,0 +1,290 @@ +--- +description: Use this topic to help manage Windows and Windows Server technologies with Windows PowerShell. +external help file: SmbServerConfiguration.cdxml-help.xml +Module Name: SmbClientAccessToServer +ms.date: 02/22/2024 +online version: https://learn.microsoft.com/powershell/module/smbshare/grant-smbclientaccesstoserver?view=windowsserver2022-ps&wt.mc_id=ps-gethelp +schema: 2.0.0 +title: Grant-SmbClientAccessToServer +--- + +# Grant-SmbClientAccessToServer + +## SYNOPSIS +Allow access to a computer or set of computers for SMB over QUIC's client access control feature on +an SMB Server. + +## SYNTAX + +### Query + +``` +Grant-SmbClientAccessToServer [-Name] -IdentifierType + -Identifier [-Description ] [-Force] [-CimSession ] + [-ThrottleLimit ] [-AsJob] [-WhatIf] [-Confirm] [] +``` + +### InputObject + +``` +Grant-SmbClientAccessToServer -InputObject -IdentifierType + -Identifier [-Description ] [-Force] [-CimSession ] + [-ThrottleLimit ] [-AsJob] [-WhatIf] [-Confirm] [] +``` + +## DESCRIPTION + +The `Grant-SmbClientAccessToServer` cmdlet is used to allow SMB clients to access a specified +server. When you run this cmdlet, it'll add a new rule to the server's firewall to allow incoming +SMB traffic from the specified client IP address. If you need to revoke access to the server in the +future, you can use the `Revoke-SmbClientAccessToServer` cmdlet. + +## EXAMPLES + +### Example 1: Grant SMB client access to a server + +```powershell +$params = @{ + Name = "Server01" + IdentifierType = "ISSUER" + Identifier = "CN=MyCertificateIssuer" + Description = "Allow access from client for LabSvr" + Force = $true +} +Grant-SmbClientAccessToServer @params +``` + +This example grants SMB client access to a server named `Server01` based on the client's +certificate. The **Description** parameter is used to provide a description of the rule being added +to the server's firewall. This command runs without prompting for confirmation. + +## PARAMETERS + +### -AsJob + +Runs the cmdlet as a background job. Use this parameter to run commands that take a long time to +complete. + +```yaml +Type: SwitchParameter +Parameter Sets: (All) +Aliases: + +Required: False +Position: Named +Default value: None +Accept pipeline input: False +Accept wildcard characters: False +``` + +### -CimSession + +Runs the cmdlet in a remote session or on a remote computer. Enter a computer name or a session +object, such as the output of a [New-CimSession](/powershell/module/cimcmdlets/new-cimsession) or +[Get-CimSession](/powershell/module/cimcmdlets/get-cimsession) cmdlet. The default is the +current session on the local computer. + +```yaml +Type: CimSession[] +Parameter Sets: (All) +Aliases: Session + +Required: False +Position: Named +Default value: None +Accept pipeline input: False +Accept wildcard characters: False +``` + +### -Description + +Used to provide a description of the rule being added to the server's firewall when you use the +`Grant-SmbClientAccessToServer` cmdlet. This can be useful if you need to keep track of which +clients have been granted access to a server, or if you need to provide additional information +about the rule for documentation purposes. + +```yaml +Type: String +Parameter Sets: (All) +Aliases: + +Required: False +Position: Named +Default value: None +Accept pipeline input: False +Accept wildcard characters: False +``` + +### -Force + +Forces the command to run without asking for user confirmation. + +```yaml +Type: SwitchParameter +Parameter Sets: (All) +Aliases: + +Required: False +Position: Named +Default value: None +Accept pipeline input: False +Accept wildcard characters: False +``` + +### -Identifier + +Specifies the identity of the client that is being granted access to the SMB server. This parameter +takes a string value that represents the identity of the client. The format of the string value +will depend on the **IdentifierType** parameter that you're using. + +```yaml +Type: String +Parameter Sets: (All) +Aliases: + +Required: True +Position: Named +Default value: None +Accept pipeline input: False +Accept wildcard characters: False +``` + +### -IdentifierType + +Specifies the type of identifier that you're using to identify a client. The valid values for the +**IdentifierType** parameter are: + +- SHA256 +- ISSUER + +If you're using the `SHA256` identifier type, you're specifying a hash value that uniquely +identifies the client. If you're using the `ISSUER` identifier type, you're specifying the issuer +of the client's certificate. + +```yaml +Type: IdentifierType +Parameter Sets: (All) +Aliases: +Accepted values: SHA256, ISSUER + +Required: True +Position: Named +Default value: None +Accept pipeline input: False +Accept wildcard characters: False +``` + +### -InputObject + +Specifies the input object that's used in a pipeline command. + +```yaml +Type: CimInstance[] +Parameter Sets: InputObject +Aliases: + +Required: True +Position: Named +Default value: None +Accept pipeline input: True (ByValue) +Accept wildcard characters: False +``` + +### -Name + +Specifies a fully-qualified DNS name or NetBIOS name that must match the certificate's subject name +or an entry in the certificate's subject alternative names. + +```yaml +Type: String +Parameter Sets: Query +Aliases: + +Required: True +Position: 1 +Default value: None +Accept pipeline input: True (ByPropertyName) +Accept wildcard characters: False +``` + +### -ThrottleLimit + +Specifies the maximum number of concurrent operations that can be established to run the cmdlet. If +this parameter is omitted or a value of `0` is entered, then Windows PowerShell calculates an +optimum throttle limit for the cmdlet based on the number of CIM cmdlets that are running on the +computer. + +The throttle limit applies only to the current cmdlet, not to the session or to the computer. + +```yaml +Type: Int32 +Parameter Sets: (All) +Aliases: + +Required: False +Position: Named +Default value: None +Accept pipeline input: False +Accept wildcard characters: False +``` + +### -Confirm + +Prompts you for confirmation before running the cmdlet. + +```yaml +Type: SwitchParameter +Parameter Sets: (All) +Aliases: cf + +Required: False +Position: Named +Default value: False +Accept pipeline input: False +Accept wildcard characters: False +``` + +### -WhatIf + +Shows what would happen if the cmdlet runs. The cmdlet isn't run. + +```yaml +Type: SwitchParameter +Parameter Sets: (All) +Aliases: wi + +Required: False +Position: Named +Default value: False +Accept pipeline input: False +Accept wildcard characters: False +``` + +### CommonParameters + +This cmdlet supports the common parameters: -Debug, -ErrorAction, -ErrorVariable, +-InformationAction, -InformationVariable, -OutVariable, -OutBuffer, -PipelineVariable, -Verbose, +-WarningAction, and -WarningVariable. For more information, see +[about_CommonParameters](/powershell/module/microsoft.powershell.core/about/about_commonparameters). + +## INPUTS + +### System.String[] + +### Microsoft.Management.Infrastructure.CimInstance[] + +## OUTPUTS + +### Microsoft.Management.Infrastructure.CimInstance[] + +## NOTES + +## RELATED LINKS + +[Block-SmbClientAccessToServer](Block-SmbClientAccessToServer.md) + +[Get-SmbClientAccessToServer](Get-SmbClientAccessToServer.md) + +[Revoke-SmbClientAccessToServer](Revoke-SmbClientAccessToServer.md) + +[Unblock-SmbClientAccessToServer](Unblock-SmbClientAccessToServer.md) diff --git a/docset/winserver2022-ps/smbshare/New-SmbClientCertificateMapping.md b/docset/winserver2022-ps/smbshare/New-SmbClientCertificateMapping.md new file mode 100644 index 0000000000..25bc2bfbe4 --- /dev/null +++ b/docset/winserver2022-ps/smbshare/New-SmbClientCertificateMapping.md @@ -0,0 +1,322 @@ +--- +description: Use this topic to help manage Windows and Windows Server technologies with Windows PowerShell. +external help file: SmbClientCertificateMapping.cdxml-help.xml +Module Name: SmbShare +ms.date: 02/22/2024 +online version: https://learn.microsoft.com/powershell/module/smbshare/new-smbclientcertificatemapping?view=windowsserver2022-ps&wt.mc_id=ps-gethelp +schema: 2.0.0 +title: New-SmbClientCertificateMapping +--- + +# New-SmbClientCertificateMapping + +## SYNOPSIS +Creates a new client certificate mapping for the Server Message Block (SMB) protocol. + +## SYNTAX + +``` +New-SmbClientCertificateMapping [-Namespace] [-Thumbprint ] [-StoreName ] + [-IssuerName ] [-Subject ] [-DisplayName ] [-Type ] [-Flags ] + [-Force] [-CimSession ] [-ThrottleLimit ] [-AsJob] [-WhatIf] [-Confirm] + [] +``` + +## DESCRIPTION + +The `New-SmbClientCertificateMapping` cmdlet creates a new client certificate mapping for the SMB +protocol. These mappings are used to authenticate clients that connect to SMB servers using +certificates. You can use this cmdlet to create a new mapping between a client certificate and an +SMB client name. + +## EXAMPLES + +### Example 1: Create a new certificate mapping for an SMB client + +```powershell +$params = @{ + Thumbprint = "a1b2c3d4e5f6g7h8" + StoreName = "My" + IssuerName = "CN=MyCertificateAuthority" + Subject = "CN=MyClientCertificate" + DisplayName = "MyClientCertificateMapping" +} +New-SmbClientCertificateMapping @params +``` + +This creates a new certificate mapping for an SMB client where a specific thumbprint, store name, +issuer name, subject, and display name are specified for the certificate mapping. + +For example, if you have an SMB client named `MySMBClient` that needs to connect to a server using +a specific certificate, you could use this cmdlet to create a certificate mapping that associates +the client with the certificate. + +## PARAMETERS + +### -AsJob + +Runs the cmdlet as a background job. Use this parameter to run commands that take a long time to +complete. + +```yaml +Type: SwitchParameter +Parameter Sets: (All) +Aliases: + +Required: False +Position: Named +Default value: None +Accept pipeline input: False +Accept wildcard characters: False +``` + +### -CimSession + +Runs the cmdlet in a remote session or on a remote computer. Enter a computer name or a session +object, such as the output of a [New-CimSession](/powershell/module/cimcmdlets/new-cimsession) +or [Get-CimSession](/powershell/module/cimcmdlets/get-cimsession) cmdlet. The default is the +current session on the local computer. + +```yaml +Type: CimSession[] +Parameter Sets: (All) +Aliases: Session + +Required: False +Position: Named +Default value: None +Accept pipeline input: False +Accept wildcard characters: False +``` + +### -DisplayName + +Specifies the friendly name of the certificate. + +```yaml +Type: String[] +Parameter Sets: (All) +Aliases: + +Required: False +Position: Named +Default value: None +Accept pipeline input: True (ByPropertyName) +Accept wildcard characters: False +``` + +### -Flags + +Specifies if `NamedPipes` are enabled for SMB over QUIC. The acceptable values for this parameter +are: + +- `None`: Remove all flags +- `AllowNamedPipe`: Enable use of named pipes in SMB over QUIC connections for this mapping (off by + default, overrides value of the **RestrictNamedPipeAccessOverQuic** parameter) +- `DefaultCert`: Not used + +```yaml +Type: Flags[] +Parameter Sets: (All) +Aliases: +Accepted values: None, AllowNamedPipe, DefaultCert + +Required: False +Position: Named +Default value: None +Accept pipeline input: True (ByPropertyName) +Accept wildcard characters: False +``` + +### -Force + +Forces the command to run without asking for user confirmation. + +```yaml +Type: SwitchParameter +Parameter Sets: (All) +Aliases: + +Required: False +Position: Named +Default value: None +Accept pipeline input: False +Accept wildcard characters: False +``` + +### -IssuerName + +Filters the certificate mappings based on the issuer name of the certificate. + +```yaml +Type: String +Parameter Sets: (All) +Aliases: + +Required: False +Position: Named +Default value: None +Accept pipeline input: False +Accept wildcard characters: False +``` + +### -Namespace + +Specifies the namespace of the QUIC server. For example, `server1.contoso.com`. By default, the +cmdlet searches in the `root\cimv2\Security\MicrosoftTlsCertificateMappingProvider` namespace. + +```yaml +Type: String +Parameter Sets: (All) +Aliases: + +Required: True +Position: 1 +Default value: None +Accept pipeline input: True (ByPropertyName) +Accept wildcard characters: False +``` + +### -StoreName + +Specifies the path to the certificate store for the certificate. + +```yaml +Type: String[] +Parameter Sets: (All) +Aliases: + +Required: False +Position: Named +Default value: None +Accept pipeline input: True (ByPropertyName) +Accept wildcard characters: False +``` + +### -Subject + +Specifies the subject name of the certificate. + +```yaml +Type: String[] +Parameter Sets: (All) +Aliases: + +Required: False +Position: 2 +Default value: None +Accept pipeline input: True (ByPropertyName) +Accept wildcard characters: False +``` + +### -ThrottleLimit + +Specifies the maximum number of concurrent operations that can be established to run the cmdlet. If +this parameter is omitted or a value of `0` is entered, then Windows PowerShell calculates an +optimum throttle limit for the cmdlet based on the number of CIM cmdlets that are running on the +computer. The throttle limit applies only to the current cmdlet, not to the session or to the +computer. + +```yaml +Type: Int32 +Parameter Sets: (All) +Aliases: + +Required: False +Position: Named +Default value: None +Accept pipeline input: False +Accept wildcard characters: False +``` + +### -Thumbprint + +Specifies the thumbprint value of the certificate. + +```yaml +Type: String[] +Parameter Sets: (All) +Aliases: + +Required: False +Position: Named +Default value: None +Accept pipeline input: True (ByPropertyName) +Accept wildcard characters: False +``` + +### -Type + +Specifies the type of certificate mapping. The acceptable value for this parameter is: + +`QUIC`: Certificate mapping is for SMB over QUIC. + +```yaml +Type: Type[] +Parameter Sets: (All) +Aliases: +Accepted values: QUIC + +Required: False +Position: Named +Default value: None +Accept pipeline input: True (ByPropertyName) +Accept wildcard characters: False +``` + +### -Confirm + +Prompts you for confirmation before running the cmdlet. + +```yaml +Type: SwitchParameter +Parameter Sets: (All) +Aliases: cf + +Required: False +Position: Named +Default value: False +Accept pipeline input: False +Accept wildcard characters: False +``` + +### -WhatIf + +Shows what would happen if the cmdlet runs. The cmdlet isn't run. + +```yaml +Type: SwitchParameter +Parameter Sets: (All) +Aliases: wi + +Required: False +Position: Named +Default value: False +Accept pipeline input: False +Accept wildcard characters: False +``` + +### CommonParameters + +This cmdlet supports the common parameters: -Debug, -ErrorAction, -ErrorVariable, +-InformationAction, -InformationVariable, -OutVariable, -OutBuffer, -PipelineVariable, -Verbose, +-WarningAction, and -WarningVariable. For more information, see +[about_CommonParameters](/powershell/module/microsoft.powershell.core/about/about_commonparameters). + +## INPUTS + +### System.String + +## OUTPUTS + +### Microsoft.Management.Infrastructure.CimInstance + +## NOTES + +## RELATED LINKS + +[Get-SmbClientCertificateMapping](Get-SmbClientCertificateMapping.md) + +[Remove-SmbClientCertificateMapping](Remove-SmbClientCertificateMapping.md) + +[Set-SmbClientCertificateMapping](Set-SmbClientCertificateMapping.md) diff --git a/docset/winserver2022-ps/smbshare/New-SmbServerCertificateMapping.md b/docset/winserver2022-ps/smbshare/New-SmbServerCertificateMapping.md index 142230892d..416f796ca8 100644 --- a/docset/winserver2022-ps/smbshare/New-SmbServerCertificateMapping.md +++ b/docset/winserver2022-ps/smbshare/New-SmbServerCertificateMapping.md @@ -2,7 +2,7 @@ description: Use this topic to help manage Windows and Windows Server technologies with Windows PowerShell. external help file: SmbServerCertificateMapping.cdxml-help.xml Module Name: SmbShare -ms.date: 08/31/2021 +ms.date: 02/22/2024 online version: https://learn.microsoft.com/powershell/module/smbshare/new-smbservercertificatemapping?view=windowsserver2022-ps&wt.mc_id=ps-gethelp schema: 2.0.0 title: New-SmbServerCertificateMapping @@ -17,32 +17,59 @@ Creates a certificate association with the SMB server for SMB over QUIC. ``` New-SmbServerCertificateMapping [-Name] [-Thumbprint] [-StoreName] - [-Subject ] [-DisplayName ] [-Type ] [-Flags ] [-Force] - [-CimSession ] [-ThrottleLimit ] [-AsJob] [-WhatIf] [-Confirm] [] + [-Subject ] [-DisplayName ] [-Type ] [-Flags ] + [-RequireClientAuthentication ] [-SkipClientCertificateAccessCheck ] [-Force] + [-CimSession ] [-ThrottleLimit ] [-AsJob] [-WhatIf] [-Confirm] + [] ``` ## DESCRIPTION -The **New-SmbServerCertificateMapping** cmdlet associates a certificate to the SMB server for SMB over QUIC on Windows Server 2022 Datacenter: Azure Edition. This cmdlet is not used for Windows or other Windows Server editions. For more information, review [SMB over QUIC](https://aka.ms/smboverquic). + +The `New-SmbServerCertificateMapping` cmdlet associates a certificate to the SMB server for SMB +over QUIC. For more information, see [SMB over QUIC](https://aka.ms/smboverquic). + +> [!NOTE] +> +> - The **RequireClientAuthentication** and **SkipClientCertificateAccessCheck** parameters are only +> supported in Windows Server 2022 Datacenter: Azure Edition. +> +> - If the **RequireClientAuthentication** parameter is set to `$true` and +> **SkipClientCertificateAccessCheck** is set to `$false`, the server will perform both client +> certificate validation and access control checks. +> +> - If the **RequireClientAuthentication** parameter is set to `$true` and +> **SkipClientCertificateAccessCheck** is also set to `$true`, the server will perform client +> certificate validation but no access control checks. ## EXAMPLES ### Example 1 - Map a certificate located in the local machine's personal store -This command maps a certificate located in the local machine’s personal store for SMB server edge endpoint “fs2.contoso.com” using the certificate’s thumbprint. +This command maps a certificate located in the local machine's personal store for SMB server edge +endpoint `fs2.contoso.com` using the certificate's thumbprint. ```powershell -New-SmbServerCertificateMapping -Name fs2.contoso.com -Thumbprint 88032B3551FAF7DE26EFFFF814AA086E3DBD2A4F -StoreName my -Subject CN=2022-ae-02 +$params = @{ + Name = "fs2.contoso.com" + Thumbprint = "88032B3551FAF7DE26EFFFF814AA086E3DBD2A4F" + StoreName = "My" + Subject = "CN=2022-ae-02" +} +New-SmbServerCertificateMapping @params ``` + ```output -Name Subject Thumbprint DisplayName StoreName Type Flags ----- ------- ---------- ----------- --------- ---- ----- +Name Subject Thumbprint DisplayName StoreName Type Flags +---- ------- ---------- ----------- --------- ---- ----- fs2.contoso.com CN=2022-ae-02 88032B3551FAF7DE26EFFFF814AA086E3DBD2A4F 2022-ae-02 my QUIC None ``` ## PARAMETERS ### -AsJob -Runs the cmdlet as a background job. Use this parameter to run commands that take a long time to complete. + +Runs the cmdlet as a background job. Use this parameter to run commands that take a long time to +complete. ```yaml Type: SwitchParameter @@ -57,7 +84,11 @@ Accept wildcard characters: False ``` ### -CimSession -Runs the cmdlet in a remote session or on a remote computer. Enter a computer name or a session object, such as the output of a [New-CimSession](/powershell/module/cimcmdlets/new-cimsession) or [Get-CimSession](https://go.microsoft.com/fwlink/p/?LinkId=227966) cmdlet. The default is the current session on the local computer. + +Runs the cmdlet in a remote session or on a remote computer. Enter a computer name or a session +object, such as the output of a [New-CimSession](/powershell/module/cimcmdlets/new-cimsession) or +[Get-CimSession](/powershell/module/cimcmdlets/get-cimsession) cmdlet. The default is the +current session on the local computer. ```yaml Type: CimSession[] @@ -72,6 +103,7 @@ Accept wildcard characters: False ``` ### -DisplayName + Specifies a friendly name to display for the mapping. ```yaml @@ -87,11 +119,14 @@ Accept wildcard characters: False ``` ### -Flags -Specifies if Named Pipes are enabled for SMB over QUIC. The acceptable values for this parameter are: -- `None:` Remove all flags. -- `AllowNamedPipe:` Enable use of named pipes in SMB over QUIC connections for this mapping (off by default, overrides the value of RestrictNamedPipeAccessOverQuic). -- `DefaultCert:` Not used. +Specifies if Named Pipes are enabled for SMB over QUIC. The acceptable values for this parameter +are: + +- `None`: Remove all flags. +- `AllowNamedPipe`: Enable use of named pipes in SMB over QUIC connections for this mapping (off by + default, overrides the value of the **RestrictNamedpipeAccessOverQuic** parameter). +- `DefaultCert`: Not used. ```yaml Type: Flags @@ -107,6 +142,7 @@ Accept wildcard characters: False ``` ### -Force + Forces the command to run without asking for user confirmation. ```yaml @@ -122,7 +158,9 @@ Accept wildcard characters: False ``` ### -Name -Specifies a fully-qualified DNS name or NetBIOS name that must match the certificate’s subject name or an entry in the certificate’s subject alternative names. + +Specifies a fully-qualified DNS name or NetBIOS name that must match the certificate's subject name +or an entry in the certificate's subject alternative names. ```yaml Type: String @@ -136,8 +174,53 @@ Accept pipeline input: True (ByPropertyName) Accept wildcard characters: False ``` +### -RequireClientAuthentication + +Specifies whether client authentication is required for connections to the server. When this +parameter is set to `$true`, clients must present a valid certificate to connect to the server. +When it is set to `$false`, clients can connect without presenting a certificate. + +```yaml +Type: Boolean +Parameter Sets: (All) +Aliases: + +Required: False +Position: Named +Default value: None +Accept pipeline input: False +Accept wildcard characters: False +``` + +### -SkipClientCertificateAccessCheck + +Specifies whether the server should skip the check for client certificate access when a client +connects. This parameter only applies when the server certificate mapping +**RequireClientAuthentication** value is `$true`. When this parameter is set to `$true`, the server +will not perform the access control checks based on the client certificates. This can be useful in +scenarios where the server is acting as a gateway or proxy and client certificate validation is +sufficient. + +However, it can also increase the risk of security breaches. When this parameter is set to +`$false`, the server will perform the access control checks based on the client certificates in +addition to the client certificate validation before allowing the client to connect. + +```yaml +Type: Boolean +Parameter Sets: (All) +Aliases: + +Required: False +Position: Named +Default value: None +Accept pipeline input: False +Accept wildcard characters: False +``` + ### -StoreName -Specifies the path to the certificate store for the certificate. The recommended value is “My” for the local machine personal store. + +Specifies the path to the certificate store for the certificate. The recommended value is "My" for +the local machine personal store. ```yaml Type: String @@ -152,6 +235,7 @@ Accept wildcard characters: False ``` ### -Subject + Specifies the subject name of the certificate. ```yaml @@ -167,7 +251,12 @@ Accept wildcard characters: False ``` ### -ThrottleLimit -Specifies the maximum number of concurrent operations that can be established to run the cmdlet. If this parameter is omitted or a value of 0 is entered, then Windows PowerShell calculates an optimum throttle limit for the cmdlet based on the number of CIM cmdlets that are running on the computer. The throttle limit applies only to the current cmdlet, not to the session or to the computer. + +Specifies the maximum number of concurrent operations that can be established to run the cmdlet. If +this parameter is omitted or a value of `0` is entered, then Windows PowerShell calculates an +optimum throttle limit for the cmdlet based on the number of CIM cmdlets that are running on the +computer. The throttle limit applies only to the current cmdlet, not to the session or to the +computer. ```yaml Type: Int32 @@ -182,6 +271,7 @@ Accept wildcard characters: False ``` ### -Thumbprint + Specifies the thumbprint value of the certificate. ```yaml @@ -197,9 +287,10 @@ Accept wildcard characters: False ``` ### -Type -Specifies the type of certificate mapping. The acceptable value for this parameter is: -`QUIC` Certificate mapping is for SMB over QUIC. +Specifies the type of certificate mapping. The acceptable value for this parameter is: + +- `QUIC`: Certificate mapping is for SMB over QUIC. ```yaml Type: Type @@ -215,6 +306,7 @@ Accept wildcard characters: False ``` ### -Confirm + Prompts you for confirmation before running the cmdlet. ```yaml @@ -230,8 +322,8 @@ Accept wildcard characters: False ``` ### -WhatIf -Shows what would happen if the cmdlet runs. -The cmdlet is not run. + +Shows what would happen if the cmdlet runs. The cmdlet isn't run. ```yaml Type: SwitchParameter @@ -246,7 +338,11 @@ Accept wildcard characters: False ``` ### CommonParameters -This cmdlet supports the common parameters: -Debug, -ErrorAction, -ErrorVariable, -InformationAction, -InformationVariable, -OutVariable, -OutBuffer, -PipelineVariable, -Verbose, -WarningAction, and -WarningVariable. For more information, see [about_CommonParameters](https://go.microsoft.com/fwlink/?LinkID=113216). + +This cmdlet supports the common parameters: -Debug, -ErrorAction, -ErrorVariable, +-InformationAction, -InformationVariable, -OutVariable, -OutBuffer, -PipelineVariable, -Verbose, +-WarningAction, and -WarningVariable. For more information, see +[about_CommonParameters](/powershell/module/microsoft.powershell.core/about/about_commonparameters). ## INPUTS @@ -259,3 +355,9 @@ This cmdlet supports the common parameters: -Debug, -ErrorAction, -ErrorVariable ## NOTES ## RELATED LINKS + +[Get-SmbServerCertificateMapping](Get-SmbServerCertificateMapping.md) + +[Remove-SmbServerCertificateMapping](Remove-SmbServerCertificateMapping.md) + +[Set-SmbServerCertificateMapping](Set-SmbServerCertificateMapping.md) diff --git a/docset/winserver2022-ps/smbshare/New-SmbShare.md b/docset/winserver2022-ps/smbshare/New-SmbShare.md index 65d43f96ac..f2a5b88aa8 100644 --- a/docset/winserver2022-ps/smbshare/New-SmbShare.md +++ b/docset/winserver2022-ps/smbshare/New-SmbShare.md @@ -2,7 +2,7 @@ description: Use this topic to help manage Windows and Windows Server technologies with Windows PowerShell. external help file: SmbShare.cdxml-help.xml Module Name: SmbShare -ms.date: 10/20/2022 +ms.date: 02/22/2024 online version: https://learn.microsoft.com/powershell/module/smbshare/new-smbshare?view=windowsserver2022-ps&wt.mc_id=ps-gethelp schema: 2.0.0 title: New-SmbShare @@ -42,7 +42,7 @@ To delete a share that was created by this cmdlet, use the `Remove-SmbShare` cmd ```powershell $Parameters = @{ - Name = 'Public' + Name = 'VMSFiles' Path = 'D:\Public' FullAccess = 'Contoso\Administrator', 'Contoso\Contoso-HV1$' } @@ -101,36 +101,15 @@ Accept pipeline input: False Accept wildcard characters: False ``` -### -CATimeout - -Specifies the continuous availability time-out for the share. - -```yaml -Type: UInt32 -Parameter Sets: (All) -Aliases: - -Required: False -Position: Named -Default value: None -Accept pipeline input: False -Accept wildcard characters: False -``` - ### -CachingMode Specifies the caching mode of the offline files for the SMB share. There are five caching modes: -- None. -Prevents users from storing documents and programs offline. -- Manual. -Allows users to identify the documents and programs they want to store offline. -- Programs. -Automatically stores documents and programs offline. -- Documents. -Automatically stores documents offline. -- BranchCache. -Enables BranchCache and manual caching of documents on the shared folder. +- BranchCache - Enables BranchCache and manual caching of documents on the shared folder. +- Documents - Automatically stores documents offline. +- Manual - Allows users to identify the documents and programs that they want to store offline. +- Programs - Automatically stores documents and programs offline. +- None - Prevents users from storing documents and programs offline. ```yaml Type: CachingMode @@ -182,8 +161,8 @@ Accept wildcard characters: False ### -CimSession Runs the cmdlet in a remote session or on a remote computer. Enter a computer name or a session -object, such as the output of a [New-CimSession](https://go.microsoft.com/fwlink/p/?LinkId=227967) -or [Get-CimSession](https://go.microsoft.com/fwlink/p/?LinkId=227966) cmdlet. The default is the +object, such as the output of a [New-CimSession](/powershell/module/cimcmdlets/new-cimsession) +or [Get-CimSession](/powershell/module/cimcmdlets/get-cimsession) cmdlet. The default is the current session on the local computer. ```yaml @@ -335,9 +314,9 @@ Accept wildcard characters: False Specifies SMB leasing and oplock behaviors for application compatibility. The acceptable values for this parameter are: -- `Full:` Use default lease and oplock behaviors from SMB3. -- `Shared:` Grant read-caching lease but not write or handle-caching. -- `None:` No oplocks or leases, behave like SMB1 (not recommended). +- `Full`: Use default lease and oplock behaviors from SMB3. +- `Shared`: Grant read-caching lease but not write or handle-caching. +- `None`: No oplocks or leases, behave like SMB1 (not recommended). ```yaml Type: LeasingMode @@ -425,7 +404,8 @@ Accept wildcard characters: False ### -ScopeName -Specifies the scope name of the share. For use with Windows Server failover cluster file server resources. +Specifies the scope name of the share. For use with Windows Server failover cluster file server +resources. ```yaml Type: String @@ -510,8 +490,7 @@ Accept wildcard characters: False ### -WhatIf -Shows what would happen if the cmdlet runs. -The cmdlet isn't run. +Shows what would happen if the cmdlet runs. The cmdlet isn't run. > [!NOTE] > The **WhatIf** switch doesn't work with this cmdlet. @@ -533,7 +512,7 @@ Accept wildcard characters: False This cmdlet supports the common parameters: -Debug, -ErrorAction, -ErrorVariable, -InformationAction, -InformationVariable, -OutVariable, -OutBuffer, -PipelineVariable, -Verbose, -WarningAction, and -WarningVariable. For more information, see -[about_CommonParameters](https://go.microsoft.com/fwlink/?LinkID=113216). +[about_CommonParameters](/powershell/module/microsoft.powershell.core/about/about_commonparameters). ## INPUTS @@ -552,8 +531,8 @@ object that represents the SMB share. ## RELATED LINKS -[Get-SmbShare](./Get-SmbShare.md) +[Get-SmbShare](Get-SmbShare.md) -[Remove-SmbShare](./Remove-SmbShare.md) +[Remove-SmbShare](Remove-SmbShare.md) -[Set-SmbShare](./Set-SmbShare.md) +[Set-SmbShare](Set-SmbShare.md) diff --git a/docset/winserver2022-ps/smbshare/Remove-SmbClientCertificateMapping.md b/docset/winserver2022-ps/smbshare/Remove-SmbClientCertificateMapping.md new file mode 100644 index 0000000000..8cf8624e6a --- /dev/null +++ b/docset/winserver2022-ps/smbshare/Remove-SmbClientCertificateMapping.md @@ -0,0 +1,385 @@ +--- +description: Use this topic to help manage Windows and Windows Server technologies with Windows PowerShell. +external help file: SmbClientCertificateMapping.cdxml-help.xml +Module Name: SmbShare +ms.date: 02/22/2024 +online version: https://learn.microsoft.com/powershell/module/smbshare/remove-smbclientcertificatemapping?view=windowsserver2022-ps&wt.mc_id=ps-gethelp +schema: 2.0.0 +title: Remove-SmbClientCertificateMapping +--- + +# Remove-SmbClientCertificateMapping + +## SYNOPSIS +Removes an existing client certificate mapping for the Server Message Block (SMB) protocol. + +## SYNTAX + +### Query + +``` +Remove-SmbClientCertificateMapping [-Namespace] [[-Subject] ] + [[-Thumbprint] ] [[-DisplayName] ] [[-StoreName] ] + [[-IssuerName] ] [[-Type] ] [[-Flags] ] [-IncludeHidden] [-Force] + [-CimSession ] [-ThrottleLimit ] [-AsJob] [-PassThru] [-WhatIf] [-Confirm] + [] +``` + +### InputObject + +``` +Remove-SmbClientCertificateMapping -InputObject [-Force] + [-CimSession ] [-ThrottleLimit ] [-AsJob] [-PassThru] [-WhatIf] [-Confirm] + [] +``` + +## DESCRIPTION + +The `Remove-SmbClientCertificateMapping` cmdlet removes an existing client certificate mapping for +the SMB protocol. These mappings are used to authenticate clients that connect to SMB servers using +certificates. You can use this cmdlet to remove a mapping between a client certificate and an SMB +client name. + +## EXAMPLES + +### Example 1: Remove all certificate mappings from a specific store + +```powershell +Remove-SmbClientCertificateMapping -StoreName "My" -Force +``` + +This force removes all certificate mappings that have been stored in a specific certificate store. + +### Example 2: Remove a certificate mapping by thumbprint + +```powershell +Remove-SmbClientCertificateMapping -Thumbprint "MyThumbprint" -Force +``` + +This force removes a certificate mapping with a specific thumbprint. + +## PARAMETERS + +### -AsJob + +Runs the cmdlet as a background job. Use this parameter to run commands that take a long time to +complete. + +```yaml +Type: SwitchParameter +Parameter Sets: (All) +Aliases: + +Required: False +Position: Named +Default value: None +Accept pipeline input: False +Accept wildcard characters: False +``` + +### -CimSession + +Runs the cmdlet in a remote session or on a remote computer. Enter a computer name or a session +object, such as the output of a [New-CimSession](/powershell/module/cimcmdlets/new-cimsession) +or [Get-CimSession](/powershell/module/cimcmdlets/get-cimsession) cmdlet. The default is the +current session on the local computer. + +```yaml +Type: CimSession[] +Parameter Sets: (All) +Aliases: Session + +Required: False +Position: Named +Default value: None +Accept pipeline input: False +Accept wildcard characters: False +``` + +### -DisplayName + +Specifies the friendly name of the certificate. + +```yaml +Type: String[] +Parameter Sets: Query +Aliases: + +Required: False +Position: 4 +Default value: None +Accept pipeline input: True (ByPropertyName) +Accept wildcard characters: False +``` + +### -Flags + +Specifies if Named Pipes are enabled for SMB over QUIC. The acceptable values for this parameter +are: + +- `None`: Remove all flags. +- `AllowNamedPipe`: Enable use of named pipes in SMB over QUIC connections for this mapping (off by + default, overrides the value of the **RestrictNamedPipeAccessOverQuic** parameter). +- `DefaultCert`: Not used. + +```yaml +Type: Flags[] +Parameter Sets: Query +Aliases: +Accepted values: None, AllowNamedPipe, DefaultCert + +Required: False +Position: 7 +Default value: None +Accept pipeline input: True (ByPropertyName) +Accept wildcard characters: False +``` + +### -Force + +Forces the command to run without asking for user confirmation. + +```yaml +Type: SwitchParameter +Parameter Sets: (All) +Aliases: + +Required: False +Position: Named +Default value: None +Accept pipeline input: False +Accept wildcard characters: False +``` + +### -IncludeHidden + +Not used. + +```yaml +Type: SwitchParameter +Parameter Sets: Query +Aliases: + +Required: False +Position: Named +Default value: None +Accept pipeline input: False +Accept wildcard characters: False +``` + +### -InputObject + +Specifies the input object that's used in a pipeline command. + +```yaml +Type: CimInstance[] +Parameter Sets: InputObject +Aliases: + +Required: True +Position: Named +Default value: None +Accept pipeline input: True (ByValue) +Accept wildcard characters: False +``` + +### -IssuerName + +Filters the certificate mappings based on the issuer name of the certificate. + +```yaml +Type: String[] +Parameter Sets: Query +Aliases: + +Required: False +Position: 5 +Default value: None +Accept pipeline input: True (ByPropertyName) +Accept wildcard characters: False +``` + +### -Namespace + +Specifies the namespace of the QUIC server. For example, `server1.contoso.com`. By default, the +cmdlet searches in the `root\cimv2\Security\MicrosoftTlsCertificateMappingProvider` namespace. + +```yaml +Type: String[] +Parameter Sets: Query +Aliases: + +Required: True +Position: 1 +Default value: None +Accept pipeline input: True (ByPropertyName) +Accept wildcard characters: False +``` + +### -PassThru + +Returns an object representing the item with which you're working. By default, this cmdlet doesn't +generate any output. + +```yaml +Type: SwitchParameter +Parameter Sets: (All) +Aliases: + +Required: False +Position: Named +Default value: None +Accept pipeline input: False +Accept wildcard characters: False +``` + +### -StoreName + +Specifies the path to the certificate store for the certificate. The recommended value is "My" for +the local machine personal store. + +```yaml +Type: String[] +Parameter Sets: Query +Aliases: + +Required: False +Position: 5 +Default value: None +Accept pipeline input: True (ByPropertyName) +Accept wildcard characters: False +``` + +### -Subject + +Specifies the subject name of the certificate. + +```yaml +Type: String[] +Parameter Sets: Query +Aliases: + +Required: False +Position: 2 +Default value: None +Accept pipeline input: True (ByPropertyName) +Accept wildcard characters: False +``` + +### -ThrottleLimit + +Specifies the maximum number of concurrent operations that can be established to run the cmdlet. If +this parameter is omitted or a value of `0` is entered, then Windows PowerShell calculates an +optimum throttle limit for the cmdlet based on the number of CIM cmdlets that are running on the +computer. The throttle limit applies only to the current cmdlet, not to the session or to the +computer. + +```yaml +Type: Int32 +Parameter Sets: (All) +Aliases: + +Required: False +Position: Named +Default value: None +Accept pipeline input: False +Accept wildcard characters: False +``` + +### -Thumbprint + +Specifies the thumbprint value of the certificate. + +```yaml +Type: String[] +Parameter Sets: Query +Aliases: + +Required: False +Position: 3 +Default value: None +Accept pipeline input: True (ByPropertyName) +Accept wildcard characters: False +``` + +### -Type + +`QUIC`: Certificate mapping is for SMB over QUIC. + +```yaml +Type: Type[] +Parameter Sets: Query +Aliases: +Accepted values: QUIC + +Required: False +Position: 6 +Default value: None +Accept pipeline input: True (ByPropertyName) +Accept wildcard characters: False +``` + +### -Confirm + +Prompts you for confirmation before running the cmdlet. + +```yaml +Type: SwitchParameter +Parameter Sets: (All) +Aliases: cf + +Required: False +Position: Named +Default value: False +Accept pipeline input: False +Accept wildcard characters: False +``` + +### -WhatIf + +Shows what would happen if the cmdlet runs. The cmdlet isn't run. + +```yaml +Type: SwitchParameter +Parameter Sets: (All) +Aliases: wi + +Required: False +Position: Named +Default value: False +Accept pipeline input: False +Accept wildcard characters: False +``` + +### CommonParameters + +This cmdlet supports the common parameters: -Debug, -ErrorAction, -ErrorVariable, +-InformationAction, -InformationVariable, -OutVariable, -OutBuffer, -PipelineVariable, -Verbose, +-WarningAction, and -WarningVariable. For more information, see +[about_CommonParameters](/powershell/module/microsoft.powershell.core/about/about_commonparameters). + +## INPUTS + +### System.String[] + +### Microsoft.PowerShell.Cmdletization.GeneratedTypes.SmbClientCertificateMapping.Type[] + +### Microsoft.PowerShell.Cmdletization.GeneratedTypes.SmbClientCertificateMapping.Flags[] + +### Microsoft.Management.Infrastructure.CimInstance[] + +## OUTPUTS + +### Microsoft.Management.Infrastructure.CimInstance + +### Microsoft.Management.Infrastructure.CimInstance#ROOT/Microsoft/Windows/SMB/MSFT_SmbClientCertificateMapping + +## NOTES + +## RELATED LINKS + +[Get-SmbClientCertificateMapping](Get-SmbClientCertificateMapping.md) + +[New-SmbClientCertificateMapping](New-SmbClientCertificateMapping.md) + +[Set-SmbClientCertificateMapping](Set-SmbClientCertificateMapping.md) diff --git a/docset/winserver2022-ps/smbshare/Remove-SmbServerCertificateMapping.md b/docset/winserver2022-ps/smbshare/Remove-SmbServerCertificateMapping.md index 9dbd5fdd14..5d864fba82 100644 --- a/docset/winserver2022-ps/smbshare/Remove-SmbServerCertificateMapping.md +++ b/docset/winserver2022-ps/smbshare/Remove-SmbServerCertificateMapping.md @@ -2,8 +2,8 @@ description: Use this topic to help manage Windows and Windows Server technologies with Windows PowerShell. external help file: SmbServerCertificateMapping.cdxml-help.xml Module Name: SmbShare -ms.date: 08/31/2021 -online version: https://learn.microsoft.com/powershell/module/smbshare/Remove-SmbServerCertificateMapping?view=windowsserver2022-ps&wt.mc_id=ps-gethelp +ms.date: 02/22/2024 +online version: https://learn.microsoft.com/powershell/module/smbshare/remove-smbservercertificatemapping?view=windowsserver2022-ps&wt.mc_id=ps-gethelp schema: 2.0.0 title: Remove-SmbServerCertificateMapping --- @@ -16,56 +16,71 @@ Removes a certificate mapping from the SMB server for SMB over QUIC. ## SYNTAX ### Query + ``` -Remove-SmbServerCertificateMapping [-Name] [[-Subject] ] [[-Thumbprint] ] - [[-DisplayName] ] [[-StoreName] ] [[-Type] ] [[-Flags] ] [-IncludeHidden] - [-Force] [-CimSession ] [-ThrottleLimit ] [-AsJob] [-PassThru] [-WhatIf] [-Confirm] +Remove-SmbServerCertificateMapping [-Name] [[-Subject] ] + [[-Thumbprint] ] [[-DisplayName] ] [[-StoreName] ] [[-Type] ] + [[-Flags]] [[-RequireClientAuthentication] ] + [[-SkipClientCertificateAccessCheck] ] [-IncludeHidden] [-Force] + [-CimSession ] [-ThrottleLimit ] [-AsJob] [-PassThru] [-WhatIf] [-Confirm] [] ``` -### InputObject (cdxml) +### InputObject + ``` -Remove-SmbServerCertificateMapping -InputObject [-Force] [-CimSession ] - [-ThrottleLimit ] [-AsJob] [-PassThru] [-WhatIf] [-Confirm] [] +Remove-SmbServerCertificateMapping -InputObject [-Force] + [-CimSession ] [-ThrottleLimit ] [-AsJob] [-PassThru] [-WhatIf] [-Confirm] + [] ``` ## DESCRIPTION -The Remove-SmbServerCertificateMapping cmdlet removes a certificate’s mapping to the SMB server for SMB over QUIC on ‘Windows Server 2022 Datacenter: Azure Edition’. This cmdlet is not used for Windows or other Windows Server editions. For more information, review SMB over QUIC. + +The `Remove-SmbServerCertificateMapping` cmdlet removes the certificates associated with the SMB +server for SMB over QUIC. For more information, review +[SMB over QUIC](/windows-server/storage/file-server/smb-over-quic). + +> [!NOTE] +> +> - The **RequireClientAuthentication** and **SkipClientCertificateAccessCheck** parameters are only +> supported in Windows Server 2022 Datacenter: Azure Edition. +> +> - If the **RequireClientAuthentication** parameter is set to `$true` and +> **SkipClientCertificateAccessCheck** is set to `$false`, the server will perform both client +> certificate validation and access control checks. +> +> - If the **RequireClientAuthentication** parameter is set to `$true` and +> **SkipClientCertificateAccessCheck** is also set to `$true`, the server will perform client +> certificate validation but no access control checks. ## EXAMPLES ### Example 1 - Remove a certificate mapping for SMB server edge endpoint -This command removes a certificate mapping for SMB server edge endpoint “fs2.contoso.com” with a specific certificate thumbprint. - ```powershell -PS C:\> Get-SmbServerCertificateMapping +$params = @{ + Name = "fs2.contoso.com" + Thumbprint = "88032B3551FAF7DE26EFFFF814AA086E3DBD2A4F" +} +Remove-SmbServerCertificateMapping @params ``` ```output -Name Subject Thumbprint DisplayName StoreName Type Flags ----- ------- ---------- ----------- --------- ---- ----- -2022-ae-02.corp.contoso.com CN=2022-ae-02 88032B3551FAF7DE26EFFFF814AA086E3DBD2A4F 2022-ae-02 my QUIC None -fs2.contoso.com CN=2022-ae-02 88032B3551FAF7DE26EFFFF814AA086E3DBD2A4F 2022-ae-02 my QUIC None - -``` -```powershell -Remove-SmbServerCertificateMapping -Name fs2.contoso.com -Thumbprint 88032B3551FAF7DE26EFFFF814AA086E3DBD2A4F -``` - -```output -Confirm -Are you sure you want to perform this action? -Performing operation 'Delete' on Target 'SMB Server Certificate Mapping.'. +Confirm +Are you sure you want to perform this action? +Performing operation 'Delete' on Target 'SMB Server Certificate Mapping.'. [Y] Yes [A] Yes to All [N] No [L] No to All [S] Suspend [?] Help (default is "Y"): y ``` -This command removes a certificate mapping for SMB server edge endpoint “fs2.contoso.com” with a specific certificate thumbprint. +This command removes a certificate mapping for SMB server edge endpoint `fs2.contoso.com` with a +specific certificate thumbprint. ## PARAMETERS ### -AsJob -Runs the cmdlet as a background job. Use this parameter to run commands that take a long time to complete. + +Runs the cmdlet as a background job. Use this parameter to run commands that take a long time to +complete. ```yaml Type: SwitchParameter @@ -80,7 +95,11 @@ Accept wildcard characters: False ``` ### -CimSession -Runs the cmdlet in a remote session or on a remote computer. Enter a computer name or a session object, such as the output of a [`New-CimSession`](/powershell/module/cimcmdlets/new-cimsession) or [`Get-CimSession`](https://go.microsoft.com/fwlink/p/?LinkId=227966) cmdlet. The default is the current session on the local computer. + +Runs the cmdlet in a remote session or on a remote computer. Enter a computer name or a session +object, such as the output of a [`New-CimSession`](/powershell/module/cimcmdlets/new-cimsession) or +[`Get-CimSession`](/powershell/module/cimcmdlets/get-cimsession) cmdlet. The default is the +current session on the local computer. ```yaml Type: CimSession[] @@ -95,6 +114,7 @@ Accept wildcard characters: False ``` ### -DisplayName + Specifies a friendly name to display for the mapping. ```yaml @@ -110,11 +130,14 @@ Accept wildcard characters: False ``` ### -Flags -Specifies if Named Pipes are enabled for SMB over QUIC. The acceptable values for this parameter are: -- `None:` Remove all flags. -- `AllowNamedPipe:` Enable use of named pipes in SMB over QUIC connections for this mapping (off by default, overrides the value of RestrictNamedPipeAccessOverQuic). -- `DefaultCert:` Not used. +Specifies if Named Pipes are enabled for SMB over QUIC. The acceptable values for this parameter +are: + +- `None`: Remove all flags. +- `AllowNamedPipe`: Enable use of named pipes in SMB over QUIC connections for this mapping (off by + default, overrides the value of the **RestrictNamedpipeAccessOverQuic** parameter). +- `DefaultCert`: Not used. ```yaml Type: Flags[] @@ -130,6 +153,7 @@ Accept wildcard characters: False ``` ### -Force + Forces the command to run without asking for user confirmation. ```yaml @@ -145,6 +169,7 @@ Accept wildcard characters: False ``` ### -IncludeHidden + Not used. ```yaml @@ -160,11 +185,12 @@ Accept wildcard characters: False ``` ### -InputObject -Specifies the input object that is used in a pipeline command. + +Specifies the input object that's used in a pipeline command. ```yaml Type: CimInstance[] -Parameter Sets: InputObject (cdxml) +Parameter Sets: InputObject Aliases: Required: True @@ -175,7 +201,9 @@ Accept wildcard characters: False ``` ### -Name -Specifies a fully-qualified DNS name or NetBIOS name that must match the certificate’s subject name or an entry in the certificate’s subject alternative names. + +Specifies a fully-qualified DNS name or NetBIOS name that must match the certificate's subject name +or an entry in the certificate's subject alternative names. ```yaml Type: String[] @@ -190,7 +218,9 @@ Accept wildcard characters: False ``` ### -PassThru -Returns an object representing the item with which you are working. By default, this cmdlet does not generate any output. + +Returns an object representing the item with which you're working. By default, this cmdlet doesn't +generate any output. ```yaml Type: SwitchParameter @@ -204,8 +234,53 @@ Accept pipeline input: False Accept wildcard characters: False ``` +### -RequireClientAuthentication + +Specifies whether client authentication is required for connections to the server. When this +parameter is set to `$true`, clients must present a valid certificate to connect to the server. +When it is set to `$false`, clients can connect without presenting a certificate. + +```yaml +Type: Boolean[] +Parameter Sets: Query +Aliases: + +Required: False +Position: 8 +Default value: None +Accept pipeline input: True (ByPropertyName) +Accept wildcard characters: False +``` + +### -SkipClientCertificateAccessCheck + +Specifies whether the server should skip the check for client certificate access when a client +connects. This parameter only applies when the server certificate mapping +**RequireClientAuthentication** value is `$true`. When this parameter is set to `$true`, the server +will not perform the access control checks based on the client certificates. This can be useful in +scenarios where the server is acting as a gateway or proxy and client certificate validation is +sufficient. + +However, it can also increase the risk of security breaches. When this parameter is set to +`$false`, the server will perform the access control checks based on the client certificates in +addition to the client certificate validation before allowing the client to connect. + +```yaml +Type: Boolean[] +Parameter Sets: Query +Aliases: + +Required: False +Position: 9 +Default value: None +Accept pipeline input: True (ByPropertyName) +Accept wildcard characters: False +``` + ### -StoreName -Specifies the path to the certificate store for the certificate. The recommended value is “My” for the local machine personal store. + +Specifies the path to the certificate store for the certificate. The recommended value is "My" for +the local machine personal store. ```yaml Type: String[] @@ -220,6 +295,7 @@ Accept wildcard characters: False ``` ### -Subject + Specifies the subject name of the certificate. ```yaml @@ -235,7 +311,12 @@ Accept wildcard characters: False ``` ### -ThrottleLimit -Specifies the maximum number of concurrent operations that can be established to run the cmdlet. If this parameter is omitted or a value of 0 is entered, then Windows PowerShell calculates an optimum throttle limit for the cmdlet based on the number of CIM cmdlets that are running on the computer. The throttle limit applies only to the current cmdlet, not to the session or to the computer. + +Specifies the maximum number of concurrent operations that can be established to run the cmdlet. If +this parameter is omitted or a value of `0` is entered, then Windows PowerShell calculates an +optimum throttle limit for the cmdlet based on the number of CIM cmdlets that are running on the +computer. The throttle limit applies only to the current cmdlet, not to the session or to the +computer. ```yaml Type: Int32 @@ -250,6 +331,7 @@ Accept wildcard characters: False ``` ### -Thumbprint + Specifies the thumbprint value of the certificate. ```yaml @@ -265,7 +347,10 @@ Accept wildcard characters: False ``` ### -Type -`QUIC` Certificate mapping is for SMB over QUIC. + +Specifies the type of certificate mapping. The acceptable value for this parameter is: + +- `QUIC`: Certificate mapping is for SMB over QUIC. ```yaml Type: Type[] @@ -281,6 +366,7 @@ Accept wildcard characters: False ``` ### -Confirm + Prompts you for confirmation before running the cmdlet. ```yaml @@ -296,8 +382,8 @@ Accept wildcard characters: False ``` ### -WhatIf -Shows what would happen if the cmdlet runs. -The cmdlet is not run. + +Shows what would happen if the cmdlet runs. The cmdlet isn't run. ```yaml Type: SwitchParameter @@ -312,7 +398,11 @@ Accept wildcard characters: False ``` ### CommonParameters -This cmdlet supports the common parameters: -Debug, -ErrorAction, -ErrorVariable, -InformationAction, -InformationVariable, -OutVariable, -OutBuffer, -PipelineVariable, -Verbose, -WarningAction, and -WarningVariable. For more information, see [about_CommonParameters](https://go.microsoft.com/fwlink/?LinkID=113216). + +This cmdlet supports the common parameters: -Debug, -ErrorAction, -ErrorVariable, +-InformationAction, -InformationVariable, -OutVariable, -OutBuffer, -PipelineVariable, -Verbose, +-WarningAction, and -WarningVariable. For more information, see +[about_CommonParameters](/powershell/module/microsoft.powershell.core/about/about_commonparameters). ## INPUTS @@ -322,6 +412,8 @@ This cmdlet supports the common parameters: -Debug, -ErrorAction, -ErrorVariable ### Microsoft.PowerShell.Cmdletization.GeneratedTypes.SmbServerCertificateMapping.Flags[] +### System.Boolean[] + ### Microsoft.Management.Infrastructure.CimInstance[] ## OUTPUTS @@ -333,3 +425,9 @@ This cmdlet supports the common parameters: -Debug, -ErrorAction, -ErrorVariable ## NOTES ## RELATED LINKS + +[Get-SmbServerCertificateMapping](Get-SmbServerCertificateMapping.md) + +[New-SmbServerCertificateMapping](New-SmbServerCertificateMapping.md) + +[Set-SmbServerCertificateMapping](Set-SmbServerCertificateMapping.md) diff --git a/docset/winserver2022-ps/smbshare/Remove-SmbShare.md b/docset/winserver2022-ps/smbshare/Remove-SmbShare.md index f60237a742..2456be86e2 100644 --- a/docset/winserver2022-ps/smbshare/Remove-SmbShare.md +++ b/docset/winserver2022-ps/smbshare/Remove-SmbShare.md @@ -2,8 +2,8 @@ description: Use this topic to help manage Windows and Windows Server technologies with Windows PowerShell. external help file: SmbShare.cdxml-help.xml Module Name: SmbShare -ms.date: 12/20/2016 -online version: https://learn.microsoft.com/powershell/module/smbshare/remove-smbshare?view=windowsserver2022-ps&wt.mc_id=ps-gethelp +ms.date: 02/22/2024 +online version: https://learn.microsoft.com/powershell/module/smbshare/remove-smbshare?view=windowsserver2025-ps&wt.mc_id=ps-gethelp schema: 2.0.0 title: Remove-SmbShare --- @@ -16,39 +16,44 @@ Deletes the specified SMB shares. ## SYNTAX ### Query + ``` Remove-SmbShare [-Name] [[-ScopeName] ] [-SmbInstance ] [-Force] [-CimSession ] [-ThrottleLimit ] [-AsJob] [-PassThru] [-WhatIf] [-Confirm] [] ``` -### InputObject (cdxml) +### InputObject + ``` -Remove-SmbShare -InputObject [-Force] [-CimSession ] [-ThrottleLimit ] - [-AsJob] [-PassThru] [-WhatIf] [-Confirm] [] +Remove-SmbShare -InputObject [-Force] [-CimSession ] + [-ThrottleLimit ] [-AsJob] [-PassThru] [-WhatIf] [-Confirm] [] ``` ## DESCRIPTION -The **Remove-SmbShare** cmdlet deletes one or more Server Message Block (SMB) shares. -Removing an SMB share forcibly disconnects all of the existing connections to the share. -Use this cmdlet with caution. -Clients that are forcibly disconnected from a share are not able to flush locally cached data before they are disconnected. -This may cause data loss. -Use the Get-SmbSession cmdlet to determine whether users are connected to a share. +The `Remove-SmbShare` cmdlet deletes one or more Server Message Block (SMB) shares. + +Removing an SMB share forcibly disconnects all of the existing connections to the share. Use this +cmdlet with caution. Clients that are forcibly disconnected from a share aren't able to flush +locally cached data before they are disconnected. This may cause data loss. Use the `Get-SmbSession` +cmdlet to determine whether users are connected to a share. ## EXAMPLES ### Example 1: Delete an SMB share -``` -PS C:\>Remove-SmbShare -Name "Data" -Confirm -Are you sure you want to perform this action? -Performing operation 'Remove-Share' on Target 'Contoso-FS,Data'. + +```powershell +Remove-SmbShare -Name "Data" + + +Confirm +Are you sure you want to perform this action? +Performing operation `Remove-Share` on Target 'Contoso-FS,Data'. [Y] Yes [A] Yes to All [N] No [L] No to All [S] Suspend [?] Help (default is "Y"): ``` -This command deletes the SMB share named Data. +This command deletes the SMB share named `Data`. ### Example 2: Delete a Windows Server failover cluster file server resource SMB share without confirmation @@ -56,17 +61,20 @@ This command deletes the SMB share named Data. Remove-SmbShare -Name "VMFiles" -ScopeName "Contoso-SO" -Force ``` -This command deletes the SMB share named VMFiles on the `Contoso-SO` file server resource without user confirmation. +This command deletes the SMB share named `VMFiles` on the `Contoso-SO` file server resource without +user confirmation. ## PARAMETERS ### -AsJob -Runs the cmdlet as a background job. Use this parameter to run commands that take a long time to complete. + +Runs the cmdlet as a background job. Use this parameter to run commands that take a long time to +complete. ```yaml Type: SwitchParameter Parameter Sets: (All) -Aliases: +Aliases: Required: False Position: Named @@ -76,9 +84,11 @@ Accept wildcard characters: False ``` ### -CimSession -Runs the cmdlet in a remote session or on a remote computer. -Enter a computer name or a session object, such as the output of a [New-CimSession](https://go.microsoft.com/fwlink/p/?LinkId=227967) or [Get-CimSession](https://go.microsoft.com/fwlink/p/?LinkId=227966) cmdlet. -The default is the current session on the local computer. + +Runs the cmdlet in a remote session or on a remote computer. Enter a computer name or a session +object, such as the output of a [New-CimSession](/powershell/module/cimcmdlets/new-cimsession) +or [Get-CimSession](/powershell/module/cimcmdlets/get-cimsession) cmdlet. The default is the +current session on the local computer. ```yaml Type: CimSession[] @@ -93,12 +103,13 @@ Accept wildcard characters: False ``` ### -Force + Forces the command to run without asking for user confirmation. ```yaml Type: SwitchParameter Parameter Sets: (All) -Aliases: +Aliases: Required: False Position: Named @@ -108,12 +119,13 @@ Accept wildcard characters: False ``` ### -InputObject -Specifies the input object that is used in a pipeline command. + +Specifies the input object that's used in a pipeline command. ```yaml Type: CimInstance[] -Parameter Sets: InputObject (cdxml) -Aliases: +Parameter Sets: InputObject +Aliases: Required: True Position: Named @@ -123,12 +135,13 @@ Accept wildcard characters: False ``` ### -Name + Specifies an array of names of SMB shares. ```yaml Type: String[] Parameter Sets: Query -Aliases: +Aliases: Required: True Position: 1 @@ -138,13 +151,14 @@ Accept wildcard characters: False ``` ### -PassThru -Returns an object representing the item with which you are working. -By default, this cmdlet does not generate any output. + +Returns an object representing the item with which you're working. By default, this cmdlet doesn't +generate any output. ```yaml Type: SwitchParameter Parameter Sets: (All) -Aliases: +Aliases: Required: False Position: Named @@ -155,12 +169,13 @@ Accept wildcard characters: False ### -ScopeName -Specifies an array of the scopes of the SMB share to delete. For use with Windows Server failover cluster file server resources. +Specifies an array of the scopes of the SMB share to delete. For use with Windows Server failover +cluster file server resources. ```yaml Type: String[] Parameter Sets: Query -Aliases: +Aliases: Required: False Position: 2 @@ -170,13 +185,14 @@ Accept wildcard characters: False ``` ### -SmbInstance -Specifies the input to this cmdlet. -You can use this parameter, or you can pipe the input to this cmdlet. + +Specifies the input to this cmdlet. You can use this parameter, or you can pipe the input to this +cmdlet. ```yaml Type: SmbInstance Parameter Sets: Query -Aliases: +Aliases: Accepted values: Default, CSV, SBL, SR Required: False @@ -187,14 +203,17 @@ Accept wildcard characters: False ``` ### -ThrottleLimit -Specifies the maximum number of concurrent operations that can be established to run the cmdlet. -If this parameter is omitted or a value of `0` is entered, then Windows PowerShell® calculates an optimum throttle limit for the cmdlet based on the number of CIM cmdlets that are running on the computer. -The throttle limit applies only to the current cmdlet, not to the session or to the computer. + +Specifies the maximum number of concurrent operations that can be established to run the cmdlet. If +this parameter is omitted or a value of `0` is entered, then Windows PowerShell calculates an +optimum throttle limit for the cmdlet based on the number of CIM cmdlets that are running on the +computer. The throttle limit applies only to the current cmdlet, not to the session or to the +computer. ```yaml Type: Int32 Parameter Sets: (All) -Aliases: +Aliases: Required: False Position: Named @@ -204,6 +223,7 @@ Accept wildcard characters: False ``` ### -Confirm + Prompts you for confirmation before running the cmdlet. ```yaml @@ -213,14 +233,14 @@ Aliases: cf Required: False Position: Named -Default value: False +Default value: None Accept pipeline input: False Accept wildcard characters: False ``` ### -WhatIf -Shows what would happen if the cmdlet runs. -The cmdlet is not run. + +Shows what would happen if the cmdlet runs. The cmdlet isn't run. ```yaml Type: SwitchParameter @@ -229,33 +249,40 @@ Aliases: wi Required: False Position: Named -Default value: False +Default value: None Accept pipeline input: False Accept wildcard characters: False ``` ### CommonParameters -This cmdlet supports the common parameters: -Debug, -ErrorAction, -ErrorVariable, -InformationAction, -InformationVariable, -OutVariable, -OutBuffer, -PipelineVariable, -Verbose, -WarningAction, and -WarningVariable. For more information, see [about_CommonParameters](https://go.microsoft.com/fwlink/?LinkID=113216). + +This cmdlet supports the common parameters: -Debug, -ErrorAction, -ErrorVariable, +-InformationAction, -InformationVariable, -OutVariable, -OutBuffer, -PipelineVariable, -Verbose, +-WarningAction, and -WarningVariable. For more information, see +[about_CommonParameters](/powershell/module/microsoft.powershell.core/about/about_commonparameters). ## INPUTS ### Microsoft.Management.Infrastructure.CimInstance#ROOT/Microsoft/Windows/SMB/MSFT_SmbShare -The `Microsoft.Management.Infrastructure.CimInstance` object is a wrapper class that displays Windows Management Instrumentation (WMI) objects. -The path after the pound sign (`#`) provides the namespace and class name for the underlying WMI object. + +The `Microsoft.Management.Infrastructure.CimInstance` object is a wrapper class that displays +Windows Management Instrumentation (WMI) objects. The path after the pound sign (`#`) provides the +namespace and class name for the underlying WMI object. ## OUTPUTS ### Microsoft.Management.Infrastructure.CimInstance#ROOT/Microsoft/Windows/SMB/MSFT_SmbShare -The `Microsoft.Management.Infrastructure.CimInstance` object is a wrapper class that displays Windows Management Instrumentation (WMI) objects. -The path after the pound sign (`#`) provides the namespace and class name for the underlying WMI object. + +The `Microsoft.Management.Infrastructure.CimInstance` object is a wrapper class that displays +Windows Management Instrumentation (WMI) objects. The path after the pound sign (`#`) provides the +namespace and class name for the underlying WMI object. ## NOTES ## RELATED LINKS -[Get-SmbShare](./Get-SmbShare.md) - -[New-SmbShare](./New-SmbShare.md) +[Get-SmbShare](Get-SmbShare.md) -[Set-SmbShare](./Set-SmbShare.md) +[New-SmbShare](New-SmbShare.md) +[Set-SmbShare](Set-SmbShare.md) diff --git a/docset/winserver2022-ps/smbshare/Reset-SmbServerConfiguration.md b/docset/winserver2022-ps/smbshare/Reset-SmbServerConfiguration.md index e1583389f9..27e3456890 100644 --- a/docset/winserver2022-ps/smbshare/Reset-SmbServerConfiguration.md +++ b/docset/winserver2022-ps/smbshare/Reset-SmbServerConfiguration.md @@ -2,8 +2,8 @@ description: Use this topic to help manage Windows and Windows Server technologies with Windows PowerShell. external help file: SmbServerConfiguration.cdxml-help.xml Module Name: SmbShare -ms.date: 10/20/2022 -online version: http://go.microsoft.com/fwlink/?LinkID=241959 +ms.date: 02/22/2024 +online version: https://learn.microsoft.com/powershell/module/smbshare/reset-smbserverconfiguration?view=windowsserver2022-ps&wt.mc_id=ps-gethelp schema: 2.0.0 title: Reset-SmbServerConfiguration --- @@ -17,15 +17,15 @@ Resets the Server Message Block (SMB) server configuration parameters to their d ``` Reset-SmbServerConfiguration [-All] [-AnnounceComment] [-AnnounceServer] [-AsynchronousCredits] - [-AuditSmb1Access] [-AutoShareServer] [-AutoShareWorkstation] [-CachedOpenLimit] - [-DisableCompression] [-DisableSmbEncryptionOnSecureConnection] [-DurableHandleV2TimeoutInSeconds] - [-EnableDownlevelTimewarp] [-EnableLeasing] [-EnableMultiChannel] [-EnableOplocks] - [-EnableSMB2Protocol] [-EnableSMBQUIC] [-EnableStrictNameChecking] [-EncryptData] - [-EncryptionCiphers] [-IrpStackSize] [-KeepAliveTime] [-MaxChannelPerSession] [-MaxMpxCount] - [-MaxSessionPerConnection] [-MaxThreadsPerQueue] [-MaxWorkItems] [-NullSessionShares] - [-OplockBreakWait] [-PendingClientTimeoutInSeconds] [-RejectUnencryptedAccess] - [-RequestCompression] [-RestrictNamedpipeAccessViaQuic] [-ServerHidden] [-Smb2CreditsMax] - [-Smb2CreditsMin] [-SmbServerNameHardeningLevel] [-TreatHostAsStableStorage] + [-AuditClientCertificateAccess] [-AuditSmb1Access] [-AutoShareServer] [-AutoShareWorkstation] + [-CachedOpenLimit] [-DisableCompression] [-DisableSmbEncryptionOnSecureConnection] + [-DurableHandleV2TimeoutInSeconds] [-EnableDownlevelTimewarp] [-EnableLeasing] + [-EnableMultiChannel] [-EnableOplocks] [-EnableSMB2Protocol] [-EnableSMBQUIC] + [-EnableStrictNameChecking] [-EncryptData] [-EncryptionCiphers] [-IrpStackSize] [-KeepAliveTime] + [-MaxChannelPerSession] [-MaxMpxCount] [-MaxSessionPerConnection] [-MaxThreadsPerQueue] + [-MaxWorkItems] [-NullSessionShares] [-OplockBreakWait] [-PendingClientTimeoutInSeconds] + [-RejectUnencryptedAccess] [-RequestCompression] [-RestrictNamedpipeAccessViaQuic] [-ServerHidden] + [-Smb2CreditsMax] [-Smb2CreditsMin] [-SmbServerNameHardeningLevel] [-TreatHostAsStableStorage] [-ValidateAliasNotCircular] [-ValidateShareScope] [-ValidateShareScopeNotAliased] [-ValidateTargetName] [-Force] [-CimSession ] [-ThrottleLimit ] [-AsJob] [-WhatIf] [-Confirm] [] @@ -39,6 +39,7 @@ default values. For more information on SMB server and protocol specifications, and [[MS-SMB2]:Server Message Block (SMB) Protocol Versions 2 and3](/openspecs/windows_protocols/ms-smb2/5606ad47-5ee0-437a-817e-70c366052962). > [!NOTE] +> > - This cmdlet is available beginning with 2022-06 Cumulative Update for Microsoft server operating > system version 21H2 for x64-based Systems > ([KB5014665](https://support.microsoft.com/help/5014665)), and Cumulative Update for Windows 11, @@ -143,6 +144,25 @@ Accept pipeline input: False Accept wildcard characters: False ``` +### -AuditClientCertificateAccess + +Resets the SMB over QUIC client access control audit events to its default value. + +> [!NOTE] +> Devices running Windows 11 version 22H2 and earlier may not have access to this parameter. + +```yaml +Type: SwitchParameter +Parameter Sets: (All) +Aliases: + +Required: False +Position: Named +Default value: None +Accept pipeline input: False +Accept wildcard characters: False +``` + ### -AuditSmb1Access Resets the auditing of SMB version 1 protocol behavior to its default value. @@ -210,8 +230,8 @@ Accept wildcard characters: False ### -CimSession Runs the cmdlet in a remote session or on a remote computer. Enter a computer name or a session -object, such as the output of a [New-CimSession](https://go.microsoft.com/fwlink/p/?LinkId=227967) -or [Get-CimSession](https://go.microsoft.com/fwlink/p/?LinkId=227966) cmdlet. The default is the +object, such as the output of a [New-CimSession](/powershell/module/cimcmdlets/new-cimsession) +or [Get-CimSession](/powershell/module/cimcmdlets/get-cimsession) cmdlet. The default is the current session on the local computer. ```yaml @@ -844,7 +864,7 @@ Accept wildcard characters: False This cmdlet supports the common parameters: -Debug, -ErrorAction, -ErrorVariable, -InformationAction, -InformationVariable, -OutVariable, -OutBuffer, -PipelineVariable, -Verbose, -WarningAction, and -WarningVariable. For more information, see -[about_CommonParameters](http://go.microsoft.com/fwlink/?LinkID=113216). +[about_CommonParameters](/powershell/module/microsoft.powershell.core/about/about_commonparameters). ## INPUTS @@ -858,6 +878,6 @@ This cmdlet supports the common parameters: -Debug, -ErrorAction, -ErrorVariable ## RELATED LINKS -[Get-SmbServerConfiguration](./Get-SmbServerConfiguration.md) +[Get-SmbServerConfiguration](Get-SmbServerConfiguration.md) -[Set-SmbServerConfiguration](./Set-SmbServerConfiguration.md) +[Set-SmbServerConfiguration](Set-SmbServerConfiguration.md) diff --git a/docset/winserver2022-ps/smbshare/Revoke-SmbClientAccessToServer.md b/docset/winserver2022-ps/smbshare/Revoke-SmbClientAccessToServer.md new file mode 100644 index 0000000000..4d7becee8a --- /dev/null +++ b/docset/winserver2022-ps/smbshare/Revoke-SmbClientAccessToServer.md @@ -0,0 +1,262 @@ +--- +description: Use this topic to help manage Windows and Windows Server technologies with Windows PowerShell. +external help file: SmbClientAccessToServer.cdxml-help.xml +Module Name: SmbShare +ms.date: 02/22/2024 +online version: https://learn.microsoft.com/powershell/module/smbshare/revoke-smbclientaccesstoserver?view=windowsserver2022-ps&wt.mc_id=ps-gethelp +schema: 2.0.0 +title: Revoke-SmbClientAccessToServer +--- + +# Revoke-SmbClientAccessToServer + +## SYNOPSIS +Revokes SMB client access to a specified server. + +## SYNTAX + +### Query + +``` +Revoke-SmbClientAccessToServer [-Name] -IdentifierType + -Identifier [-Force] [-CimSession ] [-ThrottleLimit ] [-AsJob] + [-WhatIf] [-Confirm] [] +``` + +### InputObject + +``` +Revoke-SmbClientAccessToServer -InputObject -IdentifierType + -Identifier [-Force] [-CimSession ] [-ThrottleLimit ] [-AsJob] + [-WhatIf] [-Confirm] [] +``` + +## DESCRIPTION + +The `Revoke-SmbClientAccessToServer` cmdlet is used to remove a previously granted access rule for +SMB clients to a specified server. When you run this cmdlet, it'll remove the firewall rule that +allows incoming SMB traffic from the specified client IP address. If you need to grant access to +the server again in the future, you can use the `Grant-SmbClientAccessToServer` cmdlet. + +## EXAMPLES + +### Example 1 + +```powershell +Revoke-SmbClientAccessToServer -Name "Server01" -IdentifierType "SHA256" -Identifier "ClientHash" +``` + +This example revokes the SMB client access to a server named `Server01` for a client with a +specific SHA256 hash value. + +## PARAMETERS + +### -AsJob + +Runs the cmdlet as a background job. Use this parameter to run commands that take a long time to +complete. + +```yaml +Type: SwitchParameter +Parameter Sets: (All) +Aliases: + +Required: False +Position: Named +Default value: None +Accept pipeline input: False +Accept wildcard characters: False +``` + +### -CimSession + +Runs the cmdlet in a remote session or on a remote computer. Enter a computer name or a session +object, such as the output of a [New-CimSession](/powershell/module/cimcmdlets/new-cimsession) or +[Get-CimSession](/powershell/module/cimcmdlets/get-cimsession) cmdlet. The default is the +current session on the local computer. + +```yaml +Type: CimSession[] +Parameter Sets: (All) +Aliases: Session + +Required: False +Position: Named +Default value: None +Accept pipeline input: False +Accept wildcard characters: False +``` + +### -Force + +Forces the command to run without asking for user confirmation. + +```yaml +Type: SwitchParameter +Parameter Sets: (All) +Aliases: + +Required: False +Position: Named +Default value: None +Accept pipeline input: False +Accept wildcard characters: False +``` + +### -Identifier + +Specifies the identity of the client that is being granted access to the SMB server. This parameter +takes a string value that represents the identity of the client. The format of the string value +will depend on the **IdentifierType** parameter that you're using. + +```yaml +Type: String +Parameter Sets: (All) +Aliases: + +Required: True +Position: Named +Default value: None +Accept pipeline input: False +Accept wildcard characters: False +``` + +### -IdentifierType + +Specifies the type of identifier that you're using to identify a client. The valid values for the +**IdentifierType** parameter are: + +- SHA256 +- ISSUER + +If you're using the `SHA256` identifier type, you're specifying a hash value that uniquely +identifies the client. If you're using the `ISSUER` identifier type, you're specifying the issuer +of the client's certificate. + +```yaml +Type: IdentifierType +Parameter Sets: (All) +Aliases: +Accepted values: SHA256, ISSUER + +Required: True +Position: Named +Default value: None +Accept pipeline input: False +Accept wildcard characters: False +``` + +### -InputObject + +Specifies the input object that's used in a pipeline command. + +```yaml +Type: CimInstance[] +Parameter Sets: InputObject +Aliases: + +Required: True +Position: Named +Default value: None +Accept pipeline input: True (ByValue) +Accept wildcard characters: False +``` + +### -Name + +Specifies a fully-qualified DNS name or NetBIOS name that must match the certificate's subject name +or an entry in the certificate's subject alternative names. + +```yaml +Type: String +Parameter Sets: Query +Aliases: + +Required: True +Position: 1 +Default value: None +Accept pipeline input: True (ByPropertyName) +Accept wildcard characters: False +``` + +### -ThrottleLimit + +Specifies the maximum number of concurrent operations that can be established to run the cmdlet. If +this parameter is omitted or a value of `0` is entered, then Windows PowerShell calculates an +optimum throttle limit for the cmdlet based on the number of CIM cmdlets that are running on the +computer. + +The throttle limit applies only to the current cmdlet, not to the session or to the computer. + +```yaml +Type: Int32 +Parameter Sets: (All) +Aliases: + +Required: False +Position: Named +Default value: None +Accept pipeline input: False +Accept wildcard characters: False +``` + +### -Confirm + +Prompts you for confirmation before running the cmdlet. + +```yaml +Type: SwitchParameter +Parameter Sets: (All) +Aliases: cf + +Required: False +Position: Named +Default value: False +Accept pipeline input: False +Accept wildcard characters: False +``` + +### -WhatIf + +Shows what would happen if the cmdlet runs. The cmdlet isn't run. + +```yaml +Type: SwitchParameter +Parameter Sets: (All) +Aliases: wi + +Required: False +Position: Named +Default value: False +Accept pipeline input: False +Accept wildcard characters: False +``` + +### CommonParameters + +This cmdlet supports the common parameters: -Debug, -ErrorAction, -ErrorVariable, +-InformationAction, -InformationVariable, -OutVariable, -OutBuffer, -PipelineVariable, -Verbose, +-WarningAction, and -WarningVariable. For more information, see +[about_CommonParameters](/powershell/module/microsoft.powershell.core/about/about_commonparameters). + +## INPUTS + +### System.String[] + +### Microsoft.Management.Infrastructure.CimInstance[] + +## OUTPUTS + +### Microsoft.Management.Infrastructure.CimInstance[] + +## NOTES + +## RELATED LINKS + +[Block-SmbClientAccessToServer](Block-SmbClientAccessToServer.md) + +[Get-SmbClientAccessToServer](Get-SmbClientAccessToServer.md) + +[Grant-SmbClientAccessToServer](Grant-SmbClientAccessToServer.md) + +[Unblock-SmbClientAccessToServer](Unblock-SmbClientAccessToServer.md) diff --git a/docset/winserver2022-ps/smbshare/Set-SmbClientCertificateMapping.md b/docset/winserver2022-ps/smbshare/Set-SmbClientCertificateMapping.md new file mode 100644 index 0000000000..cf8e9f3a80 --- /dev/null +++ b/docset/winserver2022-ps/smbshare/Set-SmbClientCertificateMapping.md @@ -0,0 +1,244 @@ +--- +description: Use this topic to help manage Windows and Windows Server technologies with Windows PowerShell. +external help file: SmbClientCertificateMapping.cdxml-help.xml +Module Name: SmbShare +ms.date: 02/22/2024 +online version: https://learn.microsoft.com/powershell/module/smbshare/set-smbclientcertificatemapping?view=windowsserver2022-ps&wt.mc_id=ps-gethelp +schema: 2.0.0 +title: Set-SmbClientCertificateMapping +--- + +# Set-SmbClientCertificateMapping + +## SYNOPSIS +Configures an existing client certificate mapping for the Server Message Block (SMB) protocol. + +## SYNTAX + +``` +Set-SmbClientCertificateMapping [-Namespace] [-Flags ] [-Thumbprint ] + [-StoreName ] [-IssuerName ] [-CimSession ] + [-ThrottleLimit ] [-AsJob] [-WhatIf] [-Confirm] [] +``` + +## DESCRIPTION + +The `Set-SmbClientCertificateMapping` cmdlet modifies an existing client certificate mapping for +the SMB protocol. These mappings are used to authenticate clients that connect to SMB servers using +certificates. You can use this cmdlet to modify an existing mapping between a client certificate +and an SMB client name. + +## EXAMPLES + +### Example 1: Update the issuer name for a certificate mapping + +```powershell +Set-SmbClientCertificateMapping -Thumbprint "1234567890abcdef" -IssuerName "CN=NewIssuerName" +``` + +This updates the issuer name for a certificate mapping with a specific thumbprint. + +## PARAMETERS + +### -AsJob + +Runs the cmdlet as a background job. Use this parameter to run commands that take a long time to +complete. + +```yaml +Type: SwitchParameter +Parameter Sets: (All) +Aliases: + +Required: False +Position: Named +Default value: None +Accept pipeline input: False +Accept wildcard characters: False +``` + +### -CimSession + +Runs the cmdlet in a remote session or on a remote computer. Enter a computer name or a session +object, such as the output of a [New-CimSession](/powershell/module/cimcmdlets/new-cimsession) +or [Get-CimSession](/powershell/module/cimcmdlets/get-cimsession) cmdlet. The default is the +current session on the local computer. + +```yaml +Type: CimSession[] +Parameter Sets: (All) +Aliases: Session + +Required: False +Position: Named +Default value: None +Accept pipeline input: False +Accept wildcard characters: False +``` + +### -Flags + +Specifies if `NamedPipes` are enabled for SMB over QUIC. The acceptable values for this parameter +are: + +- `None`: Remove all flags +- `AllowNamedPipe`: Enable use of named pipes in SMB over QUIC connections for this mapping (off by + default, overrides value of the **RestrictNamedPipeAccessOverQuic** parameter) +- `DefaultCert`: Not used + +```yaml +Type: Flags[] +Parameter Sets: (All) +Aliases: +Accepted values: None, AllowNamedPipe, DefaultCert + +Required: False +Position: Named +Default value: None +Accept pipeline input: True (ByPropertyName) +Accept wildcard characters: False +``` + +### -IssuerName + +Filters the certificate mappings based on the issuer name of the certificate. + +```yaml +Type: String +Parameter Sets: (All) +Aliases: + +Required: False +Position: Named +Default value: None +Accept pipeline input: False +Accept wildcard characters: False +``` + +### -Namespace + +Specifies the namespace of the QUIC server. For example, `server1.contoso.com`. By default, the +cmdlet searches in the `root\cimv2\Security\MicrosoftTlsCertificateMappingProvider` namespace. + +```yaml +Type: String +Parameter Sets: (All) +Aliases: + +Required: True +Position: 1 +Default value: None +Accept pipeline input: True (ByPropertyName) +Accept wildcard characters: False +``` + +### -StoreName + +Specifies the path to the certificate store for the certificate. + +```yaml +Type: String[] +Parameter Sets: (All) +Aliases: + +Required: False +Position: Named +Default value: None +Accept pipeline input: True (ByPropertyName) +Accept wildcard characters: False +``` + +### -ThrottleLimit + +Specifies the maximum number of concurrent operations that can be established to run the cmdlet. If +this parameter is omitted or a value of `0` is entered, then Windows PowerShell calculates an +optimum throttle limit for the cmdlet based on the number of CIM cmdlets that are running on the +computer. The throttle limit applies only to the current cmdlet, not to the session or to the +computer. + +```yaml +Type: Int32 +Parameter Sets: (All) +Aliases: + +Required: False +Position: Named +Default value: None +Accept pipeline input: False +Accept wildcard characters: False +``` + +### -Thumbprint + +Specifies the thumbprint value of the certificate. + +```yaml +Type: String[] +Parameter Sets: (All) +Aliases: + +Required: False +Position: Named +Default value: None +Accept pipeline input: True (ByPropertyName) +Accept wildcard characters: False +``` + +### -Confirm + +Prompts you for confirmation before running the cmdlet. + +```yaml +Type: SwitchParameter +Parameter Sets: (All) +Aliases: cf + +Required: False +Position: Named +Default value: False +Accept pipeline input: False +Accept wildcard characters: False +``` + +### -WhatIf + +Shows what would happen if the cmdlet runs. The cmdlet isn't run. + +```yaml +Type: SwitchParameter +Parameter Sets: (All) +Aliases: wi + +Required: False +Position: Named +Default value: False +Accept pipeline input: False +Accept wildcard characters: False +``` + +### CommonParameters + +This cmdlet supports the common parameters: -Debug, -ErrorAction, -ErrorVariable, +-InformationAction, -InformationVariable, -OutVariable, -OutBuffer, -PipelineVariable, -Verbose, +-WarningAction, and -WarningVariable. For more information, see +[about_CommonParameters](/powershell/module/microsoft.powershell.core/about/about_commonparameters). + +## INPUTS + +### System.String + +### Microsoft.PowerShell.Cmdletization.GeneratedTypes.SmbClientCertificateMapping.Flags + +## OUTPUTS + +### System.Object + +## NOTES + +## RELATED LINKS + +[Get-SmbClientCertificateMapping](Get-SmbClientCertificateMapping.md) + +[New-SmbClientCertificateMapping](New-SmbClientCertificateMapping.md) + +[Remove-SmbClientCertificateMapping](Remove-SmbClientCertificateMapping.md) diff --git a/docset/winserver2022-ps/smbshare/Set-SmbServerCertificateMapping.md b/docset/winserver2022-ps/smbshare/Set-SmbServerCertificateMapping.md index 86e9858f1c..a51c643d09 100644 --- a/docset/winserver2022-ps/smbshare/Set-SmbServerCertificateMapping.md +++ b/docset/winserver2022-ps/smbshare/Set-SmbServerCertificateMapping.md @@ -2,8 +2,8 @@ description: Use this topic to help manage Windows and Windows Server technologies with Windows PowerShell. external help file: SmbServerCertificateMapping.cdxml-help.xml Module Name: SmbShare -ms.date: 08/21/2021 -online version: https://learn.microsoft.com/powershell/module/smbshare/Set-SmbServerCertificateMapping?view=windowsserver2022-ps&wt.mc_id=ps-gethelp +ms.date: 02/22/2024 +online version: https://learn.microsoft.com/powershell/module/smbshare/set-smbservercertificatemapping?view=windowsserver2022-ps&wt.mc_id=ps-gethelp schema: 2.0.0 title: Set-SmbServerCertificateMapping --- @@ -16,35 +16,64 @@ Modifies a certificate association with the SMB server for SMB over QUIC. ## SYNTAX ### Query + ``` Set-SmbServerCertificateMapping [-Name] [-Flags ] [-Thumbprint ] - [-StoreName ] [-CimSession ] [-ThrottleLimit ] [-AsJob] [-PassThru] [-WhatIf] - [-Confirm] [] + [-StoreName ] [-RequireClientAuthentication ] + [-SkipClientCertificateAccessCheck ] [-CimSession ] [-ThrottleLimit ] + [-AsJob] [-PassThru] [-WhatIf] [-Confirm] [] ``` -### InputObject (cdxml) +### InputObject + ``` Set-SmbServerCertificateMapping -InputObject [-Flags ] [-Thumbprint ] - [-StoreName ] [-CimSession ] [-ThrottleLimit ] [-AsJob] [-PassThru] [-WhatIf] - [-Confirm] [] + [-StoreName ] [-RequireClientAuthentication ] + [-SkipClientCertificateAccessCheck ] [-CimSession ] [-ThrottleLimit ] + [-AsJob] [-PassThru] [-WhatIf] [-Confirm] [] ``` ## DESCRIPTION -The **Set-SmbServerCertificateMapping** cmdlet modifies a certificate’s association to the SMB server for SMB over QUIC on Windows Server 2022 Datacenter: Azure Edition. This cmdlet is not used for Windows or other Windows Server editions. For more information, review [SMB over QUIC](https://aka.ms/smboverquic). + +The `Set-SmbServerCertificateMapping` cmdlet modifies a certificate's association to the SMB server +for SMB over QUIC. For more information, see [SMB over QUIC](https://aka.ms/smboverquic). + +> [!NOTE] +> +> - The **RequireClientAuthentication** and **SkipClientCertificateAccessCheck** parameters are only +> supported in Windows Server 2022 Datacenter: Azure Edition. +> +> - If the **RequireClientAuthentication** parameter is set to `$true` and +> **SkipClientCertificateAccessCheck** is set to `$false`, the server will perform both client +> certificate validation and access control checks. +> +> - If the **RequireClientAuthentication** parameter is set to `$true` and +> **SkipClientCertificateAccessCheck** is also set to `$true`, the server will perform client +> certificate validation but no access control checks. ## EXAMPLES -### Example 1 - Enable Named Pipes for the SMB over QUIC endpoint -This command enables Named Pipes for the SMB over QUIC endpoint, overriding the default behavior where Named Pipes are disabled for increased security. +### Example 1: Enable Named Pipes for the SMB over QUIC endpoint + +This command enables Named Pipes for the SMB over QUIC endpoint, overriding the default behavior +where Named Pipes are disabled for increased security. ```powershell -PS C:\> Set-SmbServerCertificateMapping -Name 2022-ae-02.corp.contoso.com -Thumbprint 88032B3551FAF7DE26EFFFF814AA086E3DBD2A4F -StoreName my -Flags AllowNamedPipe +$params = @{ + Name = "2022-ae-02.corp.contoso.com" + Thumbprint = "88032B3551FAF7DE26EFFFF814AA086E3DBD2A4F" + StoreName = "My" + Flags = "AllowNamedPipe" +} +Set-SmbServerCertificateMapping @params ``` ## PARAMETERS ### -AsJob -Runs the cmdlet as a background job. Use this parameter to run commands that take a long time to complete. + +Runs the cmdlet as a background job. Use this parameter to run commands that take a long time to +complete. ```yaml Type: SwitchParameter @@ -59,7 +88,11 @@ Accept wildcard characters: False ``` ### -CimSession -Runs the cmdlet in a remote session or on a remote computer. Enter a computer name or a session object, such as the output of a [New-CimSession](/powershell/module/cimcmdlets/new-cimsession) or [Get-CimSession](https://go.microsoft.com/fwlink/p/?LinkId=227966) cmdlet. The default is the current session on the local computer. + +Runs the cmdlet in a remote session or on a remote computer. Enter a computer name or a session +object, such as the output of a [New-CimSession](/powershell/module/cimcmdlets/new-cimsession) or +[Get-CimSession](/powershell/module/cimcmdlets/get-cimsession) cmdlet. The default is the +current session on the local computer. ```yaml Type: CimSession[] @@ -74,11 +107,14 @@ Accept wildcard characters: False ``` ### -Flags -Specifies if Named Pipes are enabled for SMB over QUIC. The acceptable values for this parameter are: -- `None:` Remove all flags. -- `AllowNamedPipe:` Enable use of named pipes in SMB over QUIC connections for this mapping (off by default, overrides the value of RestrictNamedPipeAccessOverQuic). -- `DefaultCert:` Not used. +Specifies if Named Pipes are enabled for SMB over QUIC. The acceptable values for this parameter +are: + +- `None`: Remove all flags. +- `AllowNamedPipe`: Enable use of named pipes in SMB over QUIC connections for this mapping (off by + default, overrides the value of the **RestrictNamedpipeAccessOverQuic** parameter). +- `DefaultCert`: Not used. ```yaml Type: Flags @@ -94,11 +130,12 @@ Accept wildcard characters: False ``` ### -InputObject -Specifies the input object that is used in a pipeline command. + +Specifies the input object that's used in a pipeline command. ```yaml Type: CimInstance[] -Parameter Sets: InputObject (cdxml) +Parameter Sets: InputObject Aliases: Required: True @@ -109,7 +146,9 @@ Accept wildcard characters: False ``` ### -Name -Specifies a fully-qualified DNS name or NetBIOS name that must match the certificate’s subject name or an entry in the certificate’s subject alternative names. + +Specifies a fully-qualified DNS name or NetBIOS name that must match the certificate's subject name +or an entry in the certificate's subject alternative names. ```yaml Type: String[] @@ -124,7 +163,9 @@ Accept wildcard characters: False ``` ### -PassThru -Returns an object representing the item with which you are working. By default, this cmdlet does not generate any output. + +Returns an object representing the item with which you're working. By default, this cmdlet doesn't +generate any output. ```yaml Type: SwitchParameter @@ -138,8 +179,53 @@ Accept pipeline input: False Accept wildcard characters: False ``` +### -RequireClientAuthentication + +Specifies whether client authentication is required for connections to the server. When this +parameter is set to `$true`, clients must present a valid certificate to connect to the server. +When it is set to `$false`, clients can connect without presenting a certificate. + +```yaml +Type: Boolean +Parameter Sets: (All) +Aliases: + +Required: False +Position: Named +Default value: None +Accept pipeline input: False +Accept wildcard characters: False +``` + +### -SkipClientCertificateAccessCheck + +Specifies whether the server should skip the check for client certificate access when a client +connects. This parameter only applies when the server certificate mapping +**RequireClientAuthentication** value is `$true`. When this parameter is set to `$true`, the server +will not perform the access control checks based on the client certificates. This can be useful in +scenarios where the server is acting as a gateway or proxy and client certificate validation is +sufficient. + +However, it can also increase the risk of security breaches. When this parameter is set to +`$false`, the server will perform the access control checks based on the client certificates in +addition to the client certificate validation before allowing the client to connect. + +```yaml +Type: Boolean +Parameter Sets: (All) +Aliases: + +Required: False +Position: Named +Default value: None +Accept pipeline input: False +Accept wildcard characters: False +``` + ### -StoreName -Specifies the path to the certificate store for the certificate. The recommended value is “My” for the local machine personal store. + +Specifies the path to the certificate store for the certificate. The recommended value is "My" for +the local machine personal store. ```yaml Type: String @@ -154,7 +240,12 @@ Accept wildcard characters: False ``` ### -ThrottleLimit -Specifies the maximum number of concurrent operations that can be established to run the cmdlet. If this parameter is omitted or a value of 0 is entered, then Windows PowerShell calculates an optimum throttle limit for the cmdlet based on the number of CIM cmdlets that are running on the computer. The throttle limit applies only to the current cmdlet, not to the session or to the computer. + +Specifies the maximum number of concurrent operations that can be established to run the cmdlet. If +this parameter is omitted or a value of `0` is entered, then Windows PowerShell calculates an +optimum throttle limit for the cmdlet based on the number of CIM cmdlets that are running on the +computer. The throttle limit applies only to the current cmdlet, not to the session or to the +computer. ```yaml Type: Int32 @@ -169,6 +260,7 @@ Accept wildcard characters: False ``` ### -Thumbprint + Specifies the thumbprint value of the certificate. ```yaml @@ -184,6 +276,7 @@ Accept wildcard characters: False ``` ### -Confirm + Prompts you for confirmation before running the cmdlet. ```yaml @@ -199,8 +292,8 @@ Accept wildcard characters: False ``` ### -WhatIf -Shows what would happen if the cmdlet runs. -The cmdlet is not run. + +Shows what would happen if the cmdlet runs. The cmdlet isn't run. ```yaml Type: SwitchParameter @@ -215,7 +308,11 @@ Accept wildcard characters: False ``` ### CommonParameters -This cmdlet supports the common parameters: -Debug, -ErrorAction, -ErrorVariable, -InformationAction, -InformationVariable, -OutVariable, -OutBuffer, -PipelineVariable, -Verbose, -WarningAction, and -WarningVariable. For more information, see [about_CommonParameters](https://go.microsoft.com/fwlink/?LinkID=113216). + +This cmdlet supports the common parameters: -Debug, -ErrorAction, -ErrorVariable, +-InformationAction, -InformationVariable, -OutVariable, -OutBuffer, -PipelineVariable, -Verbose, +-WarningAction, and -WarningVariable. For more information, see +[about_CommonParameters](/powershell/module/microsoft.powershell.core/about/about_commonparameters). ## INPUTS @@ -236,3 +333,9 @@ This cmdlet supports the common parameters: -Debug, -ErrorAction, -ErrorVariable ## NOTES ## RELATED LINKS + +[Get-SmbServerCertificateMapping](Get-SmbServerCertificateMapping.md) + +[New-SmbServerCertificateMapping](New-SmbServerCertificateMapping.md) + +[Remove-SmbServerCertificateMapping](Remove-SmbServerCertificateMapping.md) diff --git a/docset/winserver2022-ps/smbshare/Set-SmbServerConfiguration.md b/docset/winserver2022-ps/smbshare/Set-SmbServerConfiguration.md index fc61ca7ee8..7806d604a7 100644 --- a/docset/winserver2022-ps/smbshare/Set-SmbServerConfiguration.md +++ b/docset/winserver2022-ps/smbshare/Set-SmbServerConfiguration.md @@ -2,7 +2,7 @@ description: Use this topic to help manage Windows and Windows Server technologies with Windows PowerShell. external help file: SmbServerConfiguration.cdxml-help.xml Module Name: SmbShare -ms.date: 10/20/2022 +ms.date: 02/22/2024 online version: /powershell/module/smbshare/set-smbserverconfiguration?view=windowsserver2022-ps&wt.mc_id=ps-gethelp schema: 2.0.0 title: Set-SmbServerConfiguration @@ -17,26 +17,26 @@ Sets the Server Message Block (SMB) server configuration. ``` Set-SmbServerConfiguration [-AnnounceComment ] [-AnnounceServer ] - [-AsynchronousCredits ] [-AuditSmb1Access ] [-AutoDisconnectTimeout ] - [-AutoShareServer ] [-AutoShareWorkstation ] [-CachedOpenLimit ] - [-DisableCompression ] [-DisableSmbEncryptionOnSecureConnection ] - [-DurableHandleV2TimeoutInSeconds ] [-EnableAuthenticateUserSharing ] - [-EnableDownlevelTimewarp ] [-EnableForcedLogoff ] [-EnableLeasing ] - [-EnableMultiChannel ] [-EnableOplocks ] [-EnableSecuritySignature ] - [-EnableSMB1Protocol ] [-EnableSMB2Protocol ] [-EnableSMBQUIC ] - [-EnableStrictNameChecking ] [-EncryptData ] [-EncryptionCiphers ] - [-IrpStackSize ] [-KeepAliveTime ] [-MaxChannelPerSession ] - [-MaxMpxCount ] [-MaxSessionPerConnection ] [-MaxThreadsPerQueue ] - [-MaxWorkItems ] [-NullSessionPipes ] [-NullSessionShares ] - [-OplockBreakWait ] [-PendingClientTimeoutInSeconds ] - [-RejectUnencryptedAccess ] [-RequestCompression ] - [-RequireSecuritySignature ] [-RestrictNamedpipeAccessViaQuic ] - [-ServerHidden ] [-Smb2CreditsMax ] [-Smb2CreditsMin ] - [-SmbServerNameHardeningLevel ] [-TreatHostAsStableStorage ] - [-ValidateAliasNotCircular ] [-ValidateShareScope ] - [-ValidateShareScopeNotAliased ] [-ValidateTargetName ] [-Force] - [-CimSession ] [-ThrottleLimit ] [-AsJob] [-WhatIf] [-Confirm] - [] + [-AsynchronousCredits ] [-AuditClientCertificateAccess ] + [-AuditSmb1Access ] [-AutoDisconnectTimeout ] [-AutoShareServer ] + [-AutoShareWorkstation ] [-CachedOpenLimit ] [-DisableCompression ] + [-DisableSmbEncryptionOnSecureConnection ] [-DurableHandleV2TimeoutInSeconds ] + [-EnableAuthenticateUserSharing ] [-EnableDownlevelTimewarp ] + [-EnableForcedLogoff ] [-EnableLeasing ] [-EnableMultiChannel ] + [-EnableOplocks ] [-EnableSecuritySignature ] [-EnableSMB1Protocol ] + [-EnableSMB2Protocol ] [-EnableSMBQUIC ] [-EnableStrictNameChecking ] + [-EncryptData ] [-EncryptionCiphers ] [-IrpStackSize ] + [-KeepAliveTime ] [-MaxChannelPerSession ] [-MaxMpxCount ] + [-MaxSessionPerConnection ] [-MaxThreadsPerQueue ] [-MaxWorkItems ] + [-NullSessionPipes ] [-NullSessionShares ] [-OplockBreakWait ] + [-PendingClientTimeoutInSeconds ] [-RejectUnencryptedAccess ] + [-RequestCompression ] [-RequireSecuritySignature ] + [-RestrictNamedpipeAccessViaQuic ] [-ServerHidden ] [-Smb2CreditsMax ] + [-Smb2CreditsMin ] [-SmbServerNameHardeningLevel ] + [-TreatHostAsStableStorage ] [-ValidateAliasNotCircular ] + [-ValidateShareScope ] [-ValidateShareScopeNotAliased ] + [-ValidateTargetName ] [-Force] [-CimSession ] [-ThrottleLimit ] + [-AsJob] [-WhatIf] [-Confirm] [] ``` ## DESCRIPTION @@ -47,6 +47,7 @@ For more information on SMB server and protocol specifications, see and [[MS-SMB2]:Server Message Block (SMB) Protocol Versions 2 and 3](/openspecs/windows_protocols/ms-smb2/5606ad47-5ee0-437a-817e-70c366052962). > [!NOTE] +> > - The **EncryptionCiphers** parameter is available beginning with 2022-06 Cumulative Update for > Microsoft server operating system version 21H2 for x64-based Systems > ([KB5014665](https://support.microsoft.com/help/5014665)), and Cumulative Update for Windows 11, @@ -183,6 +184,25 @@ Accept pipeline input: False Accept wildcard characters: False ``` +### -AuditClientCertificateAccess + +Enables SMB over QUIC client access control audit events. There are three possible events: access +allowed, access denied, and error. The access allowed and access denied events list properties of +the client certificate chain and any allow and deny access control entries that apply to the +client certificates. + +```yaml +Type: SwitchParameter +Parameter Sets: (All) +Aliases: + +Required: False +Position: Named +Default value: None +Accept pipeline input: False +Accept wildcard characters: False +``` + ### -AuditSmb1Access Enables auditing of SMB version 1 protocol in Windows Event Log. diff --git a/docset/winserver2022-ps/smbshare/Set-SmbShare.md b/docset/winserver2022-ps/smbshare/Set-SmbShare.md index ce2929ed2e..7e4378228a 100644 --- a/docset/winserver2022-ps/smbshare/Set-SmbShare.md +++ b/docset/winserver2022-ps/smbshare/Set-SmbShare.md @@ -2,7 +2,7 @@ description: Use this topic to help manage Windows and Windows Server technologies with Windows PowerShell. external help file: SmbShare.cdxml-help.xml Module Name: SmbShare -ms.date: 12/20/2016 +ms.date: 02/22/2024 online version: https://learn.microsoft.com/powershell/module/smbshare/set-smbshare?view=windowsserver2022-ps&wt.mc_id=ps-gethelp schema: 2.0.0 title: Set-SmbShare @@ -16,43 +16,51 @@ Modifies the properties of the SMB share. ## SYNTAX ### Query + ``` -Set-SmbShare [-Name] [[-ScopeName] ] [-SmbInstance ] [-Description ] - [-ConcurrentUserLimit ] [-CATimeout ] [-ContinuouslyAvailable ] - [-FolderEnumerationMode ] [-CachingMode ] [-SecurityDescriptor ] - [-EncryptData ] [-CompressData ] [-LeasingMode ] [-Force] - [-CimSession ] [-ThrottleLimit ] [-AsJob] [-PassThru] [-WhatIf] [-Confirm] - [] +Set-SmbShare [-Name] [[-ScopeName] ] [-SmbInstance ] + [-Description ] [-ConcurrentUserLimit ] [-CATimeout ] + [-ContinuouslyAvailable ] [-FolderEnumerationMode ] + [-CachingMode ] [-SecurityDescriptor ] [-EncryptData ] + [-CompressData ] [-LeasingMode ] [-Force] [-CimSession ] + [-ThrottleLimit ] [-AsJob] [-PassThru] [-WhatIf] [-Confirm] [] ``` -### InputObject (cdxml) +### InputObject + ``` Set-SmbShare -InputObject [-Description ] [-ConcurrentUserLimit ] - [-CATimeout ] [-ContinuouslyAvailable ] [-FolderEnumerationMode ] - [-CachingMode ] [-SecurityDescriptor ] [-EncryptData ] [-CompressData ] - [-LeasingMode ] [-Force] [-CimSession ] [-ThrottleLimit ] [-AsJob] - [-PassThru] [-WhatIf] [-Confirm] [] + [-CATimeout ] [-ContinuouslyAvailable ] + [-FolderEnumerationMode ] [-CachingMode ] + [-SecurityDescriptor ] [-EncryptData ] [-CompressData ] + [-LeasingMode ] [-Force] [-CimSession ] [-ThrottleLimit ] + [-AsJob] [-PassThru] [-WhatIf] [-Confirm] [] ``` ## DESCRIPTION -The **Set-SmbShare** cmdlet modifies the properties of the Server Message Block (SMB) share. + +The `Set-SmbShare` cmdlet modifies the properties of the Server Message Block (SMB) share. ## EXAMPLES ### Example 1: Modify properties of an SMB share -``` -PS C:\>Set-SmbShare -Name "VMFiles" -EncryptData $True -Confirm -Are you sure you want to perform this action? -Performing operation 'Modify' on Target 'Contoso-SO,VMFiles'. + +```powershell +Set-SmbShare -Name "VMFiles" -EncryptData $True + + +Confirm +Are you sure you want to perform this action? +Performing operation 'Modify' on Target 'Contoso-SO,VMFiles'. [Y] Yes [A] Yes to All [N] No [L] No to All [S] Suspend [?] Help (default is "Y"): ``` This command modifies the properties of an SMB share. ### Example 2: Modify properties of an SMB share without confirmation -``` -PS C:\>Set-SmbShare -Name "VMFiles" -EncryptData $True -Force + +```powershell +Set-SmbShare -Name "VMFiles" -EncryptData $True -Force ``` This command modifies the properties of an SMB share without user confirmation. @@ -60,7 +68,9 @@ This command modifies the properties of an SMB share without user confirmation. ## PARAMETERS ### -AsJob -Runs the cmdlet as a background job. Use this parameter to run commands that take a long time to complete. + +Runs the cmdlet as a background job. Use this parameter to run commands that take a long time to +complete. ```yaml Type: SwitchParameter @@ -75,6 +85,7 @@ Accept wildcard characters: False ``` ### -CATimeout + Specifies the continuous availability time-out of the SMB share. ```yaml @@ -90,24 +101,19 @@ Accept wildcard characters: False ``` ### -CachingMode -Specifies the caching mode of the offline files for the SMB share. -There are five caching modes: - -- None. -Prevents users from storing documents and programs offline. -- Manual. -Allows users to identify the documents and programs that they want to store offline. -- Programs. -Automatically stores documents and programs offline. -- Documents. -Automatically stores documents offline. -- BranchCache. -Enables BranchCache and manual caching of documents on the shared folder. + +Specifies the caching mode of the offline files for the SMB share. There are five caching modes: + +- BranchCache - Enables BranchCache and manual caching of documents on the shared folder. +- Documents - Automatically stores documents offline. +- Manual - Allows users to identify the documents and programs that they want to store offline. +- Programs - Automatically stores documents and programs offline. +- None - Prevents users from storing documents and programs offline. ```yaml Type: CachingMode Parameter Sets: (All) -Aliases: +Aliases: Accepted values: None, Manual, Documents, Programs, BranchCache, Unknown Required: False @@ -118,9 +124,11 @@ Accept wildcard characters: False ``` ### -CimSession -Runs the cmdlet in a remote session or on a remote computer. -Enter a computer name or a session object, such as the output of a [New-CimSession](https://go.microsoft.com/fwlink/p/?LinkId=227967) or [Get-CimSession](https://go.microsoft.com/fwlink/p/?LinkId=227966) cmdlet. -The default is the current session on the local computer. + +Runs the cmdlet in a remote session or on a remote computer. Enter a computer name or a session +object, such as the output of a [New-CimSession](/powershell/module/cimcmdlets/new-cimsession) +or [Get-CimSession](/powershell/module/cimcmdlets/get-cimsession) cmdlet. The default is the +current session on the local computer. ```yaml Type: CimSession[] @@ -135,6 +143,7 @@ Accept wildcard characters: False ``` ### -CompressData + Indicates that the shares being enumerated should request compression from clients. ```yaml @@ -150,6 +159,7 @@ Accept wildcard characters: False ``` ### -ConcurrentUserLimit + Specifies the maximum number of concurrently connected users that the SMB share may accommodate. If this parameter is set to zero (0), then the number of users is unlimited. By default, new SMB shares have no limit on the number of concurrent connections. @@ -167,6 +177,7 @@ Accept wildcard characters: False ``` ### -ContinuouslyAvailable + Indicates whether the share is continuously available. ```yaml @@ -182,10 +193,10 @@ Accept wildcard characters: False ``` ### -Description -Specifies an optional description of the SMB share. -A description of the share can be displayed by running the Get-SmbShare cmdlet. -Specify an empty string to clear the current description. -The description may not contain more than 256 characters. + +Specifies an optional description of the SMB share. A description of the share can be displayed by +running the Get-SmbShare cmdlet. Specify an empty string to clear the current description. The +description may not contain more than 256 characters. ```yaml Type: String @@ -200,6 +211,7 @@ Accept wildcard characters: False ``` ### -EncryptData + Indicates whether the SMB share is encrypted. ```yaml @@ -215,16 +227,17 @@ Accept wildcard characters: False ``` ### -FolderEnumerationMode -Specifies which files and folders in the new SMB share will be visible to the users. -The acceptable values for this parameter are: -- AccessBased. -SMB does not the display the files and folders for a share to a user unless that user has rights to access the files and folders. -By default, access-based enumeration is disabled for new SMB shares. -- Unrestricted. -SMB displays files and folders to a user even when the user does not have permission to access those items. +Specifies which files and folders in the new SMB share will be visible to the users. The acceptable +values for this parameter are: + +- `AccessBased`: SMB doesn't the display the files and folders for a share to a user unless that + user has rights to access the files and folders. By default, access-based enumeration is disabled + for new SMB shares. +- `Unrestricted`: SMB displays files and folders to a user even when the user doesn't have + permission to access those items. -The default value is Unrestricted. +The default value is **Unrestricted**. ```yaml Type: FolderEnumerationMode @@ -240,6 +253,7 @@ Accept wildcard characters: False ``` ### -Force + Forces the command to run without asking for user confirmation. ```yaml @@ -255,11 +269,12 @@ Accept wildcard characters: False ``` ### -InputObject + Specifies the input object that is used in a pipeline command. ```yaml Type: CimInstance[] -Parameter Sets: InputObject (cdxml) +Parameter Sets: InputObject Aliases: Required: True @@ -268,21 +283,25 @@ Default value: None Accept pipeline input: True (ByValue) Accept wildcard characters: False ``` + ### -LeasingMode -Specifies SMB leasing and oplock behaviors for application compatibility. The acceptable values for this parameter are: +Specifies SMB leasing and oplock behaviors for application compatibility. The acceptable values for +this parameter are: -- `Full:` Use default lease and oplock behaviors from SMB3. -- `Shared:` Grant read-caching lease but not write or handle-caching. -- `None:` No oplocks or leases, behave like SMB1 (not recommended). +- `Full`: Use default lease and oplock behaviors from SMB3. +- `Shared`: Grant read-caching lease but not write or handle-caching. +- `None`: No oplocks or leases, behave like SMB1 (not recommended). > [!IMPORTANT] -> We do not recommend disabling oplocks, but may be required in some scenarios. For more information, see [SMB1 Product Clearinghouse](https://techcommunity.microsoft.com/t5/Storage-at-Microsoft/SMB1-Product-Clearinghouse/ba-p/426008). +> We don't recommend disabling oplocks, but may be required in some scenarios. +> For more information, see [SMB1 Product Clearinghouse](https://techcommunity.microsoft.com/t5/Storage-at-Microsoft/SMB1-Product-Clearinghouse/ba-p/426008). ```yaml Type: LeasingMode Parameter Sets: (All) -Aliases: +Aliases: +Accepted values: Full, Shared, None Required: False Position: Named @@ -292,6 +311,7 @@ Accept wildcard characters: False ``` ### -Name + Specifies the name of one or more SMB shares. ```yaml @@ -307,8 +327,9 @@ Accept wildcard characters: False ``` ### -PassThru -Returns an object representing the item with which you are working. -By default, this cmdlet does not generate any output. + +Returns an object representing the item with which you are working. By default, this cmdlet does +not generate any output. ```yaml Type: SwitchParameter @@ -323,7 +344,9 @@ Accept wildcard characters: False ``` ### -ScopeName -Specifies the scope name of the SMB share. For use with Windows Server failover cluster file server resources. + +Specifies the scope name of the SMB share. For use with Windows Server failover cluster file server +resources. ```yaml Type: String[] @@ -338,6 +361,7 @@ Accept wildcard characters: False ``` ### -SecurityDescriptor + Specifies the security descriptor for the SMB share in string format. ```yaml @@ -353,8 +377,9 @@ Accept wildcard characters: False ``` ### -SmbInstance -Specifies the input to this cmdlet. -You can use this parameter, or you can pipe the input to this cmdlet. + +Specifies the input to this cmdlet. You can use this parameter, or you can pipe the input to this +cmdlet. ```yaml Type: SmbInstance @@ -370,9 +395,12 @@ Accept wildcard characters: False ``` ### -ThrottleLimit -Specifies the maximum number of concurrent operations that can be established to run the cmdlet. -If this parameter is omitted or a value of `0` is entered, then Windows PowerShell® calculates an optimum throttle limit for the cmdlet based on the number of CIM cmdlets that are running on the computer. -The throttle limit applies only to the current cmdlet, not to the session or to the computer. + +Specifies the maximum number of concurrent operations that can be established to run the cmdlet. If +this parameter is omitted or a value of `0` is entered, then Windows PowerShell® calculates an +optimum throttle limit for the cmdlet based on the number of CIM cmdlets that are running on the +computer. The throttle limit applies only to the current cmdlet, not to the session or to the +computer. ```yaml Type: Int32 @@ -387,6 +415,7 @@ Accept wildcard characters: False ``` ### -Confirm + Prompts you for confirmation before running the cmdlet. ```yaml @@ -402,8 +431,8 @@ Accept wildcard characters: False ``` ### -WhatIf -Shows what would happen if the cmdlet runs. -The cmdlet is not run. + +Shows what would happen if the cmdlet runs. The cmdlet is not run. ```yaml Type: SwitchParameter @@ -418,7 +447,11 @@ Accept wildcard characters: False ``` ### CommonParameters -This cmdlet supports the common parameters: -Debug, -ErrorAction, -ErrorVariable, -InformationAction, -InformationVariable, -OutVariable, -OutBuffer, -PipelineVariable, -Verbose, -WarningAction, and -WarningVariable. For more information, see [about_CommonParameters](https://go.microsoft.com/fwlink/?LinkID=113216). + +This cmdlet supports the common parameters: -Debug, -ErrorAction, -ErrorVariable, +-InformationAction, -InformationVariable, -OutVariable, -OutBuffer, -PipelineVariable, -Verbose, +-WarningAction, and -WarningVariable. For more information, see +[about_CommonParameters](/powershell/module/microsoft.powershell.core/about/about_commonparameters). ## INPUTS @@ -427,14 +460,15 @@ This cmdlet supports the common parameters: -Debug, -ErrorAction, -ErrorVariable ## OUTPUTS ### Microsoft.Management.Infrastructure.CimInstance#ROOT/Microsoft/Windows/SMB/MSFT_SmbShare + This cmdlet returns a **MSFT_SmbShare** object that represents the modified share. ## NOTES ## RELATED LINKS -[Get-SmbShare](./Get-SmbShare.md) +[Get-SmbShare](Get-SmbShare.md) -[New-SmbShare](./New-SmbShare.md) +[New-SmbShare](New-SmbShare.md) -[Remove-SmbShare](./Remove-SmbShare.md) +[Remove-SmbShare](Remove-SmbShare.md) diff --git a/docset/winserver2022-ps/smbshare/Unblock-SmbClientAccessToServer.md b/docset/winserver2022-ps/smbshare/Unblock-SmbClientAccessToServer.md new file mode 100644 index 0000000000..7c5130b796 --- /dev/null +++ b/docset/winserver2022-ps/smbshare/Unblock-SmbClientAccessToServer.md @@ -0,0 +1,269 @@ +--- +description: Use this topic to help manage Windows and Windows Server technologies with Windows PowerShell. +external help file: SmbClientAccessToServer.cdxml-help.xml +Module Name: SmbShare +ms.date: 02/22/2024 +online version: https://learn.microsoft.com/powershell/module/smbshare/unblock-smbclientaccesstoserver?view=windowsserver2022-ps&wt.mc_id=ps-gethelp +schema: 2.0.0 +title: Unblock-SmbClientAccessToServer +--- + +# Unblock-SmbClientAccessToServer + +## SYNOPSIS +Unblocks SMB client access to a previously blocked server. + +## SYNTAX + +### Query + +``` +Unblock-SmbClientAccessToServer [-Name] -IdentifierType + -Identifier [-Force] [-CimSession ] [-ThrottleLimit ] [-AsJob] + [-WhatIf] [-Confirm] [] +``` + +### InputObject + +``` +Unblock-SmbClientAccessToServer -InputObject -IdentifierType + -Identifier [-Force] [-CimSession ] [-ThrottleLimit ] [-AsJob] + [-WhatIf] [-Confirm] [] +``` + +## DESCRIPTION + +The `Unblock-SmbClientAccessToServer` cmdlet is used to allow SMB clients to access a server that +was previously blocked using the `Block-SmbClientAccessToServer` cmdlet. When you run this cmdlet, +any existing block on SMB client connections to the specified server will be lifted, and new +connections will be allowed. + +## EXAMPLES + +### Example 1: Unblock SMB client access to a server + +```powershell +$params = @{ + Name = "Server01" + IdentifierType = "ISSUER" + Identifier = "CN=MyCertificateIssuer" + Force = $true +} +Unblock-SmbClientAccessToServer @params +``` + +This command unblocks SMB client access to a server named `Server01` for the based on the client's +certificate. This command runs without prompting for confirmation as the **Force** parameter is set +to `$true`. + +## PARAMETERS + +### -AsJob + +Runs the cmdlet as a background job. Use this parameter to run commands that take a long time to +complete. + +```yaml +Type: SwitchParameter +Parameter Sets: (All) +Aliases: + +Required: False +Position: Named +Default value: None +Accept pipeline input: False +Accept wildcard characters: False +``` + +### -CimSession + +Runs the cmdlet in a remote session or on a remote computer. Enter a computer name or a session +object, such as the output of a [New-CimSession](/powershell/module/cimcmdlets/new-cimsession) or +[Get-CimSession](/powershell/module/cimcmdlets/get-cimsession) cmdlet. The default is the +current session on the local computer. + +```yaml +Type: CimSession[] +Parameter Sets: (All) +Aliases: Session + +Required: False +Position: Named +Default value: None +Accept pipeline input: False +Accept wildcard characters: False +``` + +### -Force + +Forces the command to run without asking for user confirmation. + +```yaml +Type: SwitchParameter +Parameter Sets: (All) +Aliases: + +Required: False +Position: Named +Default value: None +Accept pipeline input: False +Accept wildcard characters: False +``` + +### -Identifier + +Specifies the identity of the client that is being granted access to the SMB server. This parameter +takes a string value that represents the identity of the client. The format of the string value +will depend on the **IdentifierType** parameter that you're using. + +```yaml +Type: String +Parameter Sets: (All) +Aliases: + +Required: True +Position: Named +Default value: None +Accept pipeline input: False +Accept wildcard characters: False +``` + +### -IdentifierType + +Specifies the type of identifier that you're using to identify a client. The valid values for the +**IdentifierType** parameter are: + +- SHA256 +- ISSUER + +If you're using the `SHA256` identifier type, you're specifying a hash value that uniquely +identifies the client. If you're using the `ISSUER` identifier type, you're specifying the issuer +of the client's certificate. + +```yaml +Type: IdentifierType +Parameter Sets: (All) +Aliases: +Accepted values: SHA256, ISSUER + +Required: True +Position: Named +Default value: None +Accept pipeline input: False +Accept wildcard characters: False +``` + +### -InputObject + +Specifies the input object that's used in a pipeline command. + +```yaml +Type: CimInstance[] +Parameter Sets: InputObject +Aliases: + +Required: True +Position: Named +Default value: None +Accept pipeline input: True (ByValue) +Accept wildcard characters: False +``` + +### -Name + +Specifies a fully-qualified DNS name or NetBIOS name that must match the certificate's subject name +or an entry in the certificate's subject alternative names. + +```yaml +Type: String +Parameter Sets: Query +Aliases: + +Required: True +Position: 1 +Default value: None +Accept pipeline input: True (ByPropertyName) +Accept wildcard characters: False +``` + +### -ThrottleLimit + +Specifies the maximum number of concurrent operations that can be established to run the cmdlet. If +this parameter is omitted or a value of `0` is entered, then Windows PowerShell calculates an +optimum throttle limit for the cmdlet based on the number of CIM cmdlets that are running on the +computer. + +The throttle limit applies only to the current cmdlet, not to the session or to the computer. + +```yaml +Type: Int32 +Parameter Sets: (All) +Aliases: + +Required: False +Position: Named +Default value: None +Accept pipeline input: False +Accept wildcard characters: False +``` + +### -Confirm + +Prompts you for confirmation before running the cmdlet. + +```yaml +Type: SwitchParameter +Parameter Sets: (All) +Aliases: cf + +Required: False +Position: Named +Default value: False +Accept pipeline input: False +Accept wildcard characters: False +``` + +### -WhatIf + +Shows what would happen if the cmdlet runs. The cmdlet isn't run. + +```yaml +Type: SwitchParameter +Parameter Sets: (All) +Aliases: wi + +Required: False +Position: Named +Default value: False +Accept pipeline input: False +Accept wildcard characters: False +``` + +### CommonParameters + +This cmdlet supports the common parameters: -Debug, -ErrorAction, -ErrorVariable, +-InformationAction, -InformationVariable, -OutVariable, -OutBuffer, -PipelineVariable, -Verbose, +-WarningAction, and -WarningVariable. For more information, see +[about_CommonParameters](/powershell/module/microsoft.powershell.core/about/about_commonparameters). + +## INPUTS + +### System.String[] + +### Microsoft.Management.Infrastructure.CimInstance[] + +## OUTPUTS + +### Microsoft.Management.Infrastructure.CimInstance[] + +## NOTES + +## RELATED LINKS + +[Block-SmbClientAccessToServer](Block-SmbClientAccessToServer.md) + +[Get-SmbClientAccessToServer](Get-SmbClientAccessToServer.md) + +[Grant-SmbClientAccessToServer](Grant-SmbClientAccessToServer.md) + +[Revoke-SmbClientAccessToServer](Revoke-SmbClientAccessToServer.md) diff --git a/docset/winserver2022-ps/startlayout/Import-StartLayout.md b/docset/winserver2022-ps/startlayout/Import-StartLayout.md index f874fd48ce..6a2b8e179e 100644 --- a/docset/winserver2022-ps/startlayout/Import-StartLayout.md +++ b/docset/winserver2022-ps/startlayout/Import-StartLayout.md @@ -16,12 +16,12 @@ Imports the layout of the Start into a mounted Windows image. ## SYNTAX ### Path -``` +```powershell Import-StartLayout [-LayoutPath] [-MountPath] [-WhatIf] [-Confirm] [] ``` ### LiteralPath -``` +```powershell Import-StartLayout -LayoutLiteralPath -MountLiteralPath [-WhatIf] [-Confirm] [] ``` @@ -36,6 +36,8 @@ You must have administrator rights to import a layout. In Windows 10, the Export-StartLayout cmdlet exports layouts as .xml files, and the **Import-StartLayout** cmdlet imports only .xml files. +> [!CAUTION] +> The Import-StartLayout cmdlet is deprecated in Windows 11. It has no effect on either Start or Taskbar layout. To configure the Start layout in Windows 11, see [Customize the Windows 11 Start layout](https://learn.microsoft.com/en-us/windows-hardware/customize/desktop/customize-the-windows-11-start-menu). To configure Taskbar layout in Windows 11, see [Customize the Taskbar](https://learn.microsoft.com/en-us/windows-hardware/customize/desktop/customize-the-windows-11-taskbar). ## EXAMPLES ### Example 1: Import a layout into a Windows image diff --git a/docset/winserver2025-ps/activedirectory/About/About.md b/docset/winserver2025-ps/activedirectory/About/About.md new file mode 100644 index 0000000000..449df28850 --- /dev/null +++ b/docset/winserver2025-ps/activedirectory/About/About.md @@ -0,0 +1,26 @@ +--- +description: About articles for the ActiveDirectory module. +Help Version: 3.1.0.0 +Locale: en-US +ms.date: 07/03/2024 +title: About articles +--- +# About topics + +## Description + +About topics cover a range of concepts about PowerShell. + +## About Topics + +### [about_ActiveDirectory](about_ActiveDirectory.md) +The Active Directory module is a command line interface for managing Active Directory. + +### [about_ActiveDirectory_Filter](about_ActiveDirectory_Filter.md) +Describes the syntax and behavior of the search filter supported by the Active Directory module for Windows PowerShell. + +### [about_ActiveDirectory_Identity](about_ActiveDirectory_Identity.md) +The Active Directory module for Windows PowerShell objects have a range of identifying attributes that are used for search and retrieval. + +### [about_ActiveDirectory_ObjectModel](about_ActiveDirectory_ObjectModel.md) +Describes the object model of the Active Directory module for Windows PowerShell. diff --git a/docset/winserver2025-ps/activedirectory/About/about_ActiveDirectory.md b/docset/winserver2025-ps/activedirectory/About/about_ActiveDirectory.md new file mode 100644 index 0000000000..1b7183dcd2 --- /dev/null +++ b/docset/winserver2025-ps/activedirectory/About/about_ActiveDirectory.md @@ -0,0 +1,81 @@ +--- +title: about_ActiveDirectory +ms.date: 04/22/2013 +description: The Active Directory module is a command line interface for managing Active Directory. +Locale: en-US +schema: 2.0.0 +--- + +# about_ActiveDirectory + +## SHORT DESCRIPTION + +The Active Directory module is a command line interface for managing Active +Directory. + +## LONG DESCRIPTION + +The Active Directory module for Windows PowerShell is for IT Professionals who +are administering and interfacing with Active Directory. The Active Directory +module provides an efficient way to complete many administrative, +configuration, and diagnostic tasks across Active Directory Domain Services (AD +DS) and Active Directory Lightweight Directory Services (AD LDS) instances in +their environments. The Active Directory module includes a set of Windows +PowerShell cmdlets and a provider. The provider exposes the Active Directory +database through a hierarchical navigation system, which is very similar to the +file system. As with drives in a file system, such as C:, you can connect +Windows PowerShell drives to Active Directory domains and AD LDS, as well as +Active Directory snapshots. + +### Coverage of Active Directory Module Cmdlets + +Create, Read, Update, and Delete actions are supported for Active Directory +objects by cmdlets such as `New-ADUser`, `Get-ADOrganizationalUnit`, +`Set-ADComputer`, and `Remove-ADUser`. + +Account and Password Policy Management are supported by cmdlets such as +`Enable-ADAccount`, `Unlock-ADAccount`, `New-ADServiceAccount`, +`Set-ADAccountControl`, and `Remove-ADFineGrainedPasswordPolicy`. + +Domain and Forest Management is supported by cmdlets such as `Get-ADForest`, +`Set-ADForest`, `Set-ADForestMode`, `Enable-ADOptionalFeature`, +`Get-ADDomainController`, and `Get-ADDomain`. + +### Listing the Active Directory Module Cmdlets + +To get a list of all of the Active Directory module cmdlets, run + +```powershell +Get-Command -Module ActiveDirectory +``` + +### Getting Started + +Getting started with the Active Directory module for Windows PowerShell is as +easy as clicking the following shortcut: + +Run the following command in any Windows PowerShell prompt to import the Active +Directory module: + +```powershell +Import-Module ActiveDirectory +``` + +### Overview and Conceptual Topics + +The first two of these topics offer a high level overview of the Active +Directory module and the Active Directory Provider. + +- For a brief introduction to the Active Directory provider for Windows + PowerShell, see [ActiveDirectory](/powershell/module/activedirectory). +- The following topics are conceptual support topics for the Active Directory + module cmdlets. + - For an introduction to the **Identity** parameter, which is used by the + Active Directory module cmdlets to identify objects in the directory, see + [about_ActiveDirectory_Identity](about_ActiveDirectory_Identity.md). + - For an introduction to the **Filter** parameter which is used by Active + Directory module cmdlets to search for objects in the directory, see + [about_ActiveDirectory_Filter](about_ActiveDirectory_Filter.md). + - For an introduction to the .NET Framework-based object model implemented by + the Active Directory module, see + [about_ActiveDirectory_ObjectModel](about_ActiveDirectory_ObjectModel.md). diff --git a/docset/winserver2025-ps/activedirectory/About/about_ActiveDirectory_Filter.md b/docset/winserver2025-ps/activedirectory/About/about_ActiveDirectory_Filter.md new file mode 100644 index 0000000000..23a83c0a0a --- /dev/null +++ b/docset/winserver2025-ps/activedirectory/About/about_ActiveDirectory_Filter.md @@ -0,0 +1,351 @@ +--- +title: about_ActiveDirectory_Filter +ms.date: 04/22/2013 +description: Describes the syntax and behavior of the search filter supported by the Active Directory module for Windows PowerShell. +Locale: en-US +schema: 2.0.0 +--- + +# about_ActiveDirectory_Filter + +## SHORT DESCRIPTION + +Describes the syntax and behavior of the search filter supported by the Active +Directory module for Windows PowerShell. + +## LONG DESCRIPTION + +Most get-AD* Active Directory module cmdlets use the Filter parameter to search +for objects. The Filter parameter has been implemented to replace the function +of the LDAP Filter and adds support for PowerShell variables, rich data types, +improved error checking and an Active Directory extended form of the PowerShell +Expression Language. + + +- Support for LDAP Filter Syntax + + The LDAP filter syntax is supported through the **LDAPFilter** parameter. You + will find LDAP filter examples along with the new Active Directory module + filter examples in the Filter Examples section of this topic. + + +- Search Breadth and Depth + + The breadth and depth of your filter-driven search can be modified by two + Active Directory module cmdlet parameters: **SearchBase** and **SearchScope**. + + When within the context of the Active Directory provider, if the + **Searchbase** parameter is not specified, **SearchBase** will default to the + current path. When not running under the Active Directory provider, the + **SearchBase** will default to the server's **DefaultNamingContext**. + + The **SearchScope** parameter defaults to the value `Subtree`, of the + enumerated type **ADSearchScope**. + + For more information, see the **SearchBase** and **SearchScope** parameter + descriptions on any `Get-AD*` cmdlet. + +- Search Result Behavior + + The behavior of the Active Directory module when returning results of a + search is modified by two cmdlet parameters: **ResultPageSize** and + **ResultSetSize**. + + **ResultSetSize** controls the maximum number of returned objects. + + **ResultPageSize** specifies the maximum number of objects for each returned + page of information. + + See the **ResultPageSize** and **ResultSetSize** parameter descriptions on + any `Get-AD*` cmdlet for more information. + + +- Timeout Behavior + + The following statements specify timeout conditions within the Active + Directory module and describe what can be done about a timeout them. + + The default Active Directory module timeout for all operations is 2 + minutes. + + For search operation, the Active Directory module uses paging control + with a 2-minute timeout for each page search. + + > [!NOTE] + > Because a search may involve multiple server page requests the overall + > search time may exceed 2 minutes. + + A **TimeoutException** error indicates that a timeout has occurred. + + For a search operation, you can choose to use a smaller page size, set with + the **ResultPageSize** parameter, if you are getting a **TimeoutException** + error. + + If after trying these changes you are still getting a **TimeoutException** + error, consider optimizing your filter using the guidance in the + Optimizing Filters section of this topic. + + +- Optimizing Filters + + You can enhance the search filter behavior by using these guidelines. + + - Avoid using the **Recursive** parameter as it intensifies resource usage of + the search operation. + - Avoid using bitwise AND operators and bitwise OR operators. For more + information, see the Supported Operators section of this topic. + - Avoid using the logical NOT operator. + - Break down your search into multiple queries with narrower conditions. + + For a full description of filter syntax and usage, see the Filter Syntax + section of this topic. + + +## Filter Examples + +The following section shows many examples of filter use in common queries. + +### Example 1 - Get all entries: + +- LDAP Filter Equivalent: `(objectClass=*)` + +```powershell +Get-ADObject -Filter 'ObjectClass -like "*"' +``` + +### Example 2 - Get entries containing "bob" somewhere in the common name + +- LDAP Filter Equivalent: `(cn=*bob*)` + +```powershell +Get-ADObject -Filter 'CN -like "*bob*"' +``` + +### Example 3 - Get entries with a bad password count greater than five + +- LDAP Filter Equivalent: `(&(!badpwdcount<=5)(badpwdcount=*))` + +```powershell +Get-ADUser -Filter 'badpwdcount -ge 5' +``` + +### Example 4 - Get all users with an e-mail attribute + +- LDAP Filter Equivalent: `(&(objectClass=user)(email=*))` + +```powershell +Get-ADUser -filter 'email -like "*"' +``` + +-or- + +```powershell +Get-ADObject -filter 'email -like "*" -and ObjectClass -eq "user"' +``` + +### Example 5 - Get all user entries with an e-mail attribute and a surname equal to "smith": + +- LDAP Filter Equivalent: `(&(sn=smith)(objectClass=user)(email=*))` + +```powershell +Get-ADUser -Filter 'Email -like "*" -and SurName -eq "smith"' +``` + +-or- + +```powershell +Get-ADUser -Filter 'Email -like "*" -and sn -eq "smith"' +``` + + +### Example 6 - Get all user entries with a common name that starts with "andy" and users with a common name of "steve" or "margaret" + +- LDAP Filter Equivalent: `(&(objectClass=user) | (cn=andy*)(cn=steve)(cn=margaret))` + +```powershell +Get-ADUser -Filter 'CN -like "andy*" -or CN -eq "steve" -or CN -eq "margaret"' +``` + + +This example demonstrates a more complex logic and the use of precedence +control via parenthesis. + +```powershell +Get-ADObject -Filter 'objectClass -eq "user" -and (CN -like "andy*" -or CN -eq "steve" -or CN -eq "margaret")' +``` + +### Example 7 - Get all entries without an e-mail attribute + +- LDAP Filter Equivalent: `(!(email=*))` + +```powershell +Get-ADUser -Filter '-not Email -like "*"' +``` + +-or- + +```powershell +Get-ADUser -Filter 'Email -notlike "*"' +``` + +### Example 8 - Get all users who did not logon since January 1, 2007 + +- LDAP Filter Equivalent: `(&(lastlogon<=X)(objectClass=user))` where X is + number of 100-nanosecond slices since Jan 1st 1601 + +```powershell +$date = new-object System.DateTime -ArgumentList @(2007,1,1,0,0,0) +Get-ADUser -Filter '-not LastLogon -le $date' +``` + +### Example 9 - Get all users who have logged on in the last 5 days + +- LDAP Filter Equivalent: + + ``` + (&(lastLogon>=128812906535515110) + (objectClass=user)(!(objectClass=computer))) + ``` + +```powershell +$date = (get-date) - (new-timespan -days 5) +Get-ADUser -Filter 'lastLogon -gt $date' +``` + +### Example 10 - Search for group objects that have the ADS_GROUP_TYPE_SECURITY_ENABLED flag set + +- LDAP Filter Equivalent: + `(&(objectCategory=group)(groupType:1.2.840.113556.1.4.803:=2147483648))` + +The following example query string searches for group objects that have the +ADS_GROUP_TYPE_SECURITY_ENABLED flag set. Be aware that the decimal value of +ADS_GROUP_TYPE_SECURITY_ENABLED (0x80000000 = 2147483648) is used for the +comparison value. + +```powershell +Get-ADGroup -filter 'groupType -band 0x80000000' +``` + +### Example 11 - Search the ancestry of an object + +- LDAP Filter Equivalent: + `(memberof:1.2.840.113556.1.4.1941:=(cn=Group1,OU=groupsOU,DC=x)))` + +The LDAP_MATCHING_RULE_IN_CHAIN is a matching rule OID that is designed to +provide a method to look up the ancestry of an object. Many applications using +Active Directory and AD LDS usually work with hierarchical data, which is +ordered by parent-child relationships. Previously, applications performed +transitive group expansion to figure out group membership, which used a lot of +network bandwidth. Applications made multiple round-trips to figure out if an +object fell "in the chain" if a link were traversed through to the end. + +An example of such a query is one designed to check if a user, "user1" is a +member of group "group1". "user1" may not be a direct member of group1. It +could be a member of some other group, which is a member of "group1". + +You would set the base to the user DN and the scope to base, and use the query: + +```powershell +Get-ADUser -Filter 'memberOf -RecursiveMatch "CN=Administrators, CN=Builtin,DC=Fabrikam,DC=com"' -SearchBase "CN=Administrator,CN=Users,DC=Fabrikam,DC=com" +``` + +## Filter Syntax + +The following syntax descriptions use Backus-Naur form to show the PowerShell +Expression Language for the Filter parameter. + +```Syntax + ::= "{" "}" + + ::= | + | + + + ::= | + "(" ")" + + ::= "-eq" | "-le" | "-ge" | "-ne" | "-lt" | "-gt" | + "-approx" | "-bor" | "-band" | "-recursivematch" | "-like" | + "-notlike" + + ::= "-and" | "-or" + + ::= "-not" + + ::= | + +::= < this value will be compared to the object data for + attribute using the specified filter operator +``` + + +## Supported Operators + +The following table shows frequently used search filter operators. + +| Operator | Description | LDAP Equivalent | +| ----------------- | -------------------------------------- | -------------------------- | +| `-eq` | Equal to. Wildcards not supported. | = | +| `-ne` | Not equal to. Wildcards not supported. | !x = y | +| `-approx` | Approximately equal to | ~= | +| `-le` | Lexicographically less than | <= | +| | or equal to | | +| `-lt` | Lexicographically less than | !x >= y | +| `-ge` | Lexicographically greater | >= | +| | than or equal to | | +| `-gt` | Lexicographically greater than | !x <= y | +| | | | +| `-and` | AND | & | +| `-or` | OR | | +| `-not` | NOT | ! | +| `-bor` | Bitwise OR | :1.2.840.113556.1.4.804:= | +| `-band` | Bitwise AND | :1.2.840.113556.1.4.803:= | +| `-recursivematch` | Use LDAP_MATCHING_RULE_IN_CHAIN | :1.2.840.113556.1.4.1941:= | +| `-like` | Similar to `-eq` and supports | = | +| | wildcard comparison. The only | | +| | wildcard character supported is: `*` | | +| `-notlike` | Not like. Supports wild | !x = y | +| | card comparison. | | + +> [!NOTE] +> PowerShell wildcards, other than "*", such as "?" are not supported by the +> **Filter** parameter syntax. + +### Operator Precedence + +The following listing shows the precedence of operators for filters from +highest to lowest. + +- Highest precedence: `-eq`, `-ge`, `-le`, `-approx`, `-band`, `-bor`, + `-recursivematch`, `-ne`, `-like`, `-not`, `-and` +- Lowest precedence: `-or` + +### Special Characters + +The following escape sequence should be used for specifying special characters +in AD Filter STRING data, that is, data enclosed in double or single quotes. + +| ASCII Character | Escape sequence substitute | +| --------------- | --------------------------------------------------- | +| `"` | `` `" `` (This escape sequence is only required if | +| | STRING data is enclosed in double quotes.) | +| `'` | `''` (This escape sequence is only required if | +| | STRING data is enclosed in single quotes.) | +| NUL | `\00` (This is a standard LDAP escape sequence.) | +| `\` | `\5c` (This is a standard LDAP escape sequence.) | + +### LDAP Special Characters + +ADFilter parser will automatically convert all the below characters found in +STRING data, that is data enclosed in " " or ' ' to their LDAP escape sequence. +End users need not know about these LDAP escape sequence. + +| ASCII Character | Escape sequence substitute | +| --------------- | ----------------------------------------------- | +| `*` | `\2a` (Character `*` will only be converted in | +| | -eq and -ne comparisons Users should use | +| | -like and -notlike operators for wildcard | +| | comparison.) | +| `(` | `\28` | +| `)` | `\29` | +| `/` | `\2f` | diff --git a/docset/winserver2025-ps/activedirectory/About/about_ActiveDirectory_Identity.md b/docset/winserver2025-ps/activedirectory/About/about_ActiveDirectory_Identity.md new file mode 100644 index 0000000000..c007277b19 --- /dev/null +++ b/docset/winserver2025-ps/activedirectory/About/about_ActiveDirectory_Identity.md @@ -0,0 +1,196 @@ +--- +title: about_ActiveDirectory_Identity +ms.date: 04/22/2013 +description: This article lists the identifying attributes that are used for search and retrieval supported by the Active Directory module for Windows PowerShell. +Locale: en-US +schema: 2.0.0 +--- + +# about_ActiveDirectory_Identity + +## SHORT DESCRIPTION + +The Active Directory module for Windows PowerShell objects have a range of +identifying attributes that are used for search and retrieval. + +## LONG DESCRIPTION + +In order to identify the objects in Active Directory, each object has +attributes that can be used as identifiers. In the Active Directory module, the +value of the identity of an object can be passed using the Identity parameter. +Each object type has its own set of possible types and values for use by the +Identity parameter. See the detailed description of the Identity parameter of +the given cmdlet for more information about its usage. + +When searching with the Active Directory module cmdlets, the value of the +Identity parameter, along with the values of the Server and Partition +parameters, is used to uniquely identify a single object. The Server parameter +is used to locate which server to connect with. The Partition parameter further +narrows the search to a specific partition. The Identity parameter then +resolves to a single unique object in the partition. + +Note that using the Security Accounts Manager (SAM) Account Name +(**sAMAccountName**) when targeting a global catalog port, you will not find a +user in a different domain if you are using the Identity parameter + +If more than one object is found using identity resolution, the Active +Directory module throws an error. + +For more information about the Server and Partition parameters, see the help +topics for the individual cmdlets where they are used, such as `Get-ADUser`, by +typing: + +```powershell +Get-Help Get-ADUser +``` + +### Objects and Identities + +Each object has a list of attributes that can be used as an identity for that +object. Additionally, if the object inherits from another object, then the +parent object's identities can also be used as the child object's identities. +For more information on the Active Directory object hierarchy, see +[about_ActiveDirectory_ObjectModel](about_ActiveDirectory_ObjectModel.md). + +> [!NOTE] +> For Active Directory Provider cmdlets, only an object's 'Distinguished Name' +> or 'Relative Distinguished Name' can be used as the identity. For a list of +> Active Directory Provider cmdlets, see ActiveDirectory. + +### Identity Attributes + +The following is a list of identity attributes by object type. + +- ADAccount + - Distinguished Name + - GUID (objectGUID) + - Security Identifier (objectSid) + - SAM Account Name (sAMAccountName) + +- ADComputer + - Distinguished Name + - GUID (objectGUID) + - Security Identifier (objectSid) + - Security Accounts Manager Account Name (sAMAccountName) + +- ADDirectoryServer + - Name of the server object (name) + - For AD LDS instances the syntax of a name is `$` + - For other Active Directory instances, use the value of the name property. + - Distinguished Name of the NTDS Settings object + - Distinguished Name of the server object that represents the directory + server. + - GUID (objectGUID) of server object under the configuration partition. + - GUID (objectGUID) of NTDS settings object under the configuration partition + +- ADDomain + - Distinguished Name + - GUID + - Security Identifier + - DNS domain name + - NetBIOS domain name + +- ADDomainController + - GUID (objectGUID) + - IPV4Address + - Global IPV6Address + - DNS Host Name (dNSHostName) + - Name of the server object + - Distinguished Name of the NTDS Settings object + - Distinguished Name of the server object that represents the domain controller + - GUID of NTDS settings object under the configuration partition + - GUID of server object under the configuration partition + - Distinguished Name of the computer object that represents the domain controller. + +- ADFineGrainedPasswordPolicy + - Distinguished Name + - GUID (objectGUID) + - Name (name) + +- ADForest + - Fully qualified domain name + - DNS host name + - NetBIOS name + +- ADGroup + - Distinguished Name + - GUID (objectGUID) + - Security Identifier (objectSid) + - Security Accounts Manager (SAM) Account Name (sAMAccountName) + +- ADObject + - Distinguished Name + - GUID (objectGUID) + +- ADOptionalFeature + - Distinguished Name + - Name (name) + - Feature GUID (featureGUID) + - GUID (objectGUID) + +- ADOrganizationalUnit + - Distinguished Name + - GUID (objectGUID) + +- ADPrincipal + - Distinguished Name + - GUID (objectGUID) + - Security Identifier (objectSid) + - SAM Account Name (sAMAccountName) + +- ADServiceAccount + - Distinguished Name + - GUID (objectGUID) + - Security Identifier (objectSid) + - SAM Account Name (sAMAccountName) + +- ADUser + - Distinguished Name + - GUID (objectGUID) + - Security Identifier (objectSid) + - SAM User Name (sAMUserName) + + +### Identities Formats + +Active Directory module objects have a range of identity attributes. Below is a +list of these, their types and formats. + +- Distinguished Name + - Example: CN=SaraDavis,CN=Europe,CN=Users, DC=corp,DC=contoso,DC=com + +- DNS domain name + - Example: redmond.corp.contoso.com + +- DNS Host Name (dNSHostName) + - Example: corp-DC01.corp.contoso.com + +- Feature GUID (featureGUID) + - Example: 599c3d2e-f72d-4d20-8a88-030d99495f20 + +- Fully qualified domain name + - Example: corp.contoso.com + +- Global IPV6Address + - Example: 2001:4898:0:fff:200:5efe:157.59.132.61 + +- GUID (objectGUID) + - Example: 599c3d2e-f72d-4d20-8a88-030d99495f20 + +- IPV4Address + - Example:157.59.132.61 + +- NetBIOS domain name + - Example: redmond + +- Name of the server object + - Example: corp-DC01$ + +- SAM Account Name (sAMAccountName) + - Example: saradavisreports + +- Security Identifier (objectSid) + - Example: S-1-5-21-3165297888-301567370-576410423-1103 + +- Name + - Example: Recycle Bin Feature diff --git a/docset/winserver2025-ps/activedirectory/About/about_ActiveDirectory_ObjectModel.md b/docset/winserver2025-ps/activedirectory/About/about_ActiveDirectory_ObjectModel.md new file mode 100644 index 0000000000..8535a97464 --- /dev/null +++ b/docset/winserver2025-ps/activedirectory/About/about_ActiveDirectory_ObjectModel.md @@ -0,0 +1,595 @@ +--- +title: about_ActiveDirectory_ObjectModel +ms.date: 04/22/2013 +description: Describes the object model of the Active Directory module for Windows PowerShell. +Locale: en-US +schema: 2.0.0 +--- + +# about_ActiveDirectory_ObjectModel + +## SHORT DESCRIPTION +Describes the object model of the Active Directory module for Windows +PowerShell. + +## LONG DESCRIPTION + +This topic explains the Active Directory module classes and their properties +used to model actual Active Directory attributes. It also outlines the class +hierarchy constructed from its Active Directory counterpart. The object model +establishes a data foundation for all the operations supported by Active +Directory module cmdlets. + +### Class Hierarchy + +The following list shows the class hierarchy defined in the Active Directory +module object model, with class inheritance implied by indentation. This +inheritance model allows for Active Directory cmdlets to accept a range of +object types as input. This means, for example, that the cmdlet +Get-ADPrincipalGroupMembership can accept as input any of the following +objects: ADGroup, ADAccount, ADComputer, ADServiceAccount or ADUser. This works +because of the inheritance model and guarantees that an ADUser object has all +of the properties of an ADPrincipal object. + +``` +ADEntity + ADRootDSE + ADObject + ADFineGrainedPasswordPolicy + ADOptionalFeature + ADOrganizationalUnit + ADPartition + ADDomain + ADPrincipal + ADAccount + ADComputer + ADServiceAccount + ADUser + ADGroup + ADDefaultDomainPasswordPolicy + ADForest + ADDirectoryServer + ADDomainController +``` + +### Active Directory Module Classes + +The following listing shows every Active Directory module class from the class +hierarchy listing. Each class defines a set of properties, some of which are +LDAP attributes that are retrieved by default and some are new properties +created specifically for the Active Directory module. These new properties are +derived from one or more LDAP attributes as outlined in the class listings. + + +- ADEntity - The base level class from which all other classes are derived. + - ADRootDSE - Represents the rootDSE and is derived from ADEntity. An + ADRootDSE may contain the following properties in addition to those + inherited from its parent. + - ConfigurationNamingContext - A property of type System.String, derived + from the directory attribute ConfigurationNamingContext + - CurrentTime - A property of type System.DateTime, derived from the + directory attribute CurrentTime + - DefaultNamingContext - A property of type System.String, derived from the + directory attribute DefaultNamingContext + - DnsHostName - A property of type System.String, derived from the + directory attribute DnsHostName + - DomainControllerFunctionality - A property of type + ADDomainControllerMode, derived from the directory attribute + DomainControllerFunctionality + - DomainFunctionality - A property of type ADDomainMode, derived from the + directory attribute DomainFunctionality + - DsServiceName - A property of type System.String, derived from the + directory attribute DsServiceName + - ForestFunctionality - A property of type ADForestMode, derived from the + directory attribute ForestFunctionality + - GlobalCatalogReady - A property of type System.Boolean, derived from the + directory attribute GlobalCatalogReady + - HighestCommittedUSN - A property of type System.Long, derived from the + directory attribute HighestCommittedUSN + - LdapServiceName - A property of type System.String, derived from the + directory attribute LdapServiceName + - NamingContexts - A property of type System.String, derived from the + directory attribute NamingContexts + - RootDomainNamingContext - A property of type System.String, derived from + the directory attribute RootDomainNamingContext + - SchemaNamingContext - A property of type System.String, derived from the + directory attribute SchemaNamingContext + - ServerName - A property of type System.String, derived from the directory + attribute ServerName + - SubschemaSubentry - A property of type ADObject, derived from the + directory attribute SubschemaSubentry + - SupportedCapabilities - A property of type ADObjectIdentifier, derived + from the directory attribute SupportedCapabilities + - SupportedControl - A property of type ADObjectIdentifier, derived from + the directory attribute SupportedControl + - SupportedLDAPPolicies - A property of type System.String, derived from + the directory attribute SupportedLDAPPolicies + - SupportedLDAPVersion - A property of type System.Int, derived from the + directory attribute SupportedLDAPVersion + - SupportedRootDSEOperations - A property of type + ADPropertyValueCollection, derived from the directory attribute + SupportedRootDSEOperations + - SupportedSASLMechanisms - A property of type System.String, derived from + the directory attribute SupportedSASLMechanisms + - Syncronized - A property of type System.Boolean, derived from the + directory attribute IsSynchronized. + - ADObject - Represents any object in Active Directory and is derived from + ADEntity. An ADObject may contain the following properties in addition to + those inherited from its parent. + - CanonicalName - A property of type System.String, derived from the + directory attribute: canonicalName + - CN - A property of type System.String, derived from the directory + attribute: cn + - Created - A property of type System.DateTime, derived from the directory + attribute: createTimeStamp + - Deleted - A property of type System.Boolean, derived from the directory + attribute: isDeleted + - Description - A property of type System.String, derived from the + directory attribute: description + - DisplayName - A property of type System.String, derived from the + directory attribute: displayName + - DistinguishedName - A property of type System.String, derived from the + directory attribute: distinguishedName + - LastKnownParent - A property of type System.String, derived from the + directory attribute: lastKnownParent + - Modified - A property of type System.DateTime, derived from the directory + attribute: modifyTimeStamp + - Name - A property of type System.String, derived from the directory + attribute: name + - ObjectCategory - A property of type System.String, derived from the + directory attribute: objectCategory + - ObjectClass - A property of type System.String, derived from the + directory attribute: objectClass + - ObjectGUID - A property of type System.Guid, derived from the directory + attribute: objectGUID + - ProtectedFromAccidentalDeletion - A property of type System.Boolean, + derived from the directory attributes: nTSecurityDescriptor, + sdRightsEffective, instanceType, isDeleted + - ADFineGrainedPasswordPolicy Represents a fine grained password policy + object; that is, an AD object of type msDS-PasswordSettings in AD DS and + is derived from ADObject. This class is not supported by AD LDS. An + ADFineGrainedPasswordPolicy may contain the following properties in + addition to those inherited from its parent. + - AppliesTo - A property of type System.String, derived from the + directory attribute: msDS-PSOAppliesTo + - ComplexityEnabled - A property of type System.Boolean, derived from the + directory attribute: msDS-PasswordComplexityEnabled + - LockoutDuration - A property of type System.TimeSpan, derived from the + directory attribute: msDS-LockoutDuration + - LockoutObservationWindow - A property of type System.TimeSpan, derived + from the directory attribute: msDS-LockoutObservationWindow + - LockoutThreshold - A property of type System.Int32, derived from the + directory attribute: msDS-LockoutThreshold + - MaxPasswordAge - A property of type System.TimeSpan, derived from the + directory attribute: msDS-MaximumPasswordAge + - MinPasswordAge - A property of type System.TimeSpan, derived from the + directory attribute: msDS-MinimumPasswordAge + - MinPasswordLength - A property of type System.Int32, derived from the + directory attribute: msDS-MinimumPasswordLength + - PasswordHistoryCount - A property of type System.Int32, derived from + the directory attribute: msDS-PasswordHistoryLength + - Precedence - A property of type System.Int32, derived from the + directory attribute: msDS-PasswordSettingsPrecedence + - ReversibleEncryptionEnabled - A property of type System.Boolean, + derived from the directory attribute: + msDS-PasswordReversibleEncryptionEnabled + - ADOptionalFeature Represents an optional feature, an Active Directory + object of type msDS-OptionalFeature, and is derived from ADObject. An + ADOptionalFeaturemay contain the following properties in addition to + those inherited from its parent. + - EnabledScopes - A property of type System.String, derived from the + directory attribute: msDS-EnabledFeatureBL + - FeatureGUID - A property of type System.Guid, derived from the + directory attribute: msDS-OptionalFeatureGUID + - FeatureScope - A property of type System.Int32, derived from the + directory attribute: msDS-OptionalFeatureFlags + - IsDisableable - A property of type System.Boolean, derived from the + directory attribute: msDS-OptionalFeatureFlags + - RequiredDomainMode - A property of type + Microsoft.ActiveDirectory.Management.ADDomainMode, derived from the + directory attribute: msDS-RequiredDomainBehaviorVersion + - RequiredForestMode - A property of type + Microsoft.ActiveDirectory.Management.ADForestMode, derived from the + directory attribute: msDS-RequiredForestBehaviorVersion + - ADOrganizationalUnit Represents an organizationalUnit (OU) object and is + derived from ADObject. An ADOrganizationalUnit may contain the following + properties in addition to those inherited from its parent. + - City - A property of type System.String, derived from the directory + attribute: l + - Country - A property of type System.String, derived from the directory + attribute: c + - LinkedGroupPolicyObjects - A property of type System.String, derived + from the directory attribute: gpLink. This property is not supported on + AD LDS. + - ManagedBy - A property of type System.String, derived from the + directory attribute: managedBy + - PostalCode - A property of type System.String, derived from the + directory attribute: postalCode + - State - A property of type System.String, derived from the directory + attribute: st + - StreetAddress - A property of type System.String, derived from the + directory attribute: street + - ADPartition - Represents a naming context, Configuration, Schema, Domain + or Application Partition(ND NC) and is derived from ADObject. This class + is not supported by AD LDS. An ADPartition may contain the following + properties in addition to those inherited from its parent. + - DeletedObjectsContainer - A property of type System.String, derived + from the directory attribute: DeletedObjectsContainer + - DNSRoot - A property of type System.String, derived from the directory + attribute: DNSRoot + - LostAndFoundContainer - A property of type System.String, derived from + the directory attribute: LostAndFoundContainer + - QuotasContainer - A property of type System.String, derived from the + directory attribute: QuotasContainer + - ReadOnlyReplicaDirectoryServers - A property of type System.String, + derived from the directory attribute: ReadOnlyReplicaDirectoryServers + - ReplicaDirectoryServers - A property of type System.String, derived + from the directory attribute: ReplicaDirectoryServers + - SubordinateReferences - A property of type System.String, derived from + the directory attribute: SubordinateReferences + - ADDomain - Represents a domain in AD DS or an instance in AD LDS; for + example, an Active Directory object of type domainDNS and is derived + from ADPartition. This class is not supported by AD LDS. An ADDomain + may contain the following properties in addition to those inherited + from its parent. + - AllowedDNSSuffixes - A property of type System.String, derived from + the directory attribute: msDS-AllowedDNSSuffixes + - ChildDomains - A property of type System.String, derived from the + directory attribute: ChildDomains + - ComputersContainer - A property of type System.String, derived from + the directory attribute: ComputersContainer + - DomainControllersContainer - A property of type System.String, + derived from the directory attribute: DomainControllersContainer + - DomainMode - A property of type System.Int32, derived from the + directory attribute: msDS-Behavior-Version + - DomainSID - A property of type + System.Security.Principal.SecurityIdentifier, derived from the + directory attribute: objectSid + - ForeignSecurityPrincipalsContainer - A property of type + System.String, derived from the directory attribute: + ForeignSecurityPrincipalsContainer + - Forest - A property of type System.String, derived from the directory + attribute: Forest + - InfrastructureMaster - A property of type System.String, derived from + the directory attribute: InfrastructureMaster + - LastLogonReplicationInterval - A property of type System.TimeSpan, + derived from the directory attribute: msDS-LogonTimeSyncInterval + - LinkedGroupPolicyObjects - A property of type System.String, derived + from the directory attribute: LinkedGroupPolicyObjects + - ManagedBy - A property of type System.String, derived from the + directory attribute: managedBy + - NetBIOSName - A property of type System.String, derived from the + directory attribute: NetBIOSName + - ParentDomain - A property of type System.String, derived from the + directory attribute: ParentDomain + - PDCEmulator - A property of type System.String, derived from the + directory attribute: PDCEmulator + - RIDMaster - A property of type System.String, derived from the + directory attribute: RIDMaster + - SystemsContainer - A property of type System.String, derived from the + directory attribute: SystemsContainer + - UsersContainer - A property of type System.String, derived from the + directory attribute: UsersContainer + - ADPrincipal - Represents a security principal, which is an Active + Directory object of type user, computer, group or iNetOrgPerson and is + derived from ADObject. An ADPrincipal may contain the following + properties in addition to those inherited from its parent. + - HomePage - A property of type System.String, derived from the + directory attribute: wWWHomePage + - MemberOf - A property of type System.String, derived from the + directory attribute: memberOf + - SamAccountName - A property of type System.String, derived from the + directory attribute: sAMAccountName. This property is not supported + for AD LDS. + - SID - A property of type + System.Security.Principal.SecurityIdentifier, derived from the + directory attribute: objectSid + - SIDHistory - A property of type + System.Security.Principal.SecurityIdentifier, derived from the + directory attribute: sIDHistory. This property is not supported for + AD LDS. + - ADAccount - Represents a security account; that is, an Active + Directory object of type user, computer or iNetOrgPerson and is + derived from ADPrincipal. An ADAccount may contain the following + properties in addition to those inherited from its parent. + - AccountExpirationDate - A property of type System.DateTime, derived + from the directory attribute: accountExpires + - AccountLockoutTime - A property of type System.DateTime, derived + from the directory attribute: lockoutTime + - AccountNotDelegated - A property of type System.Boolean, derived + from the directory attributes: userAccountControl, + msDS-User-Account-Control-Computed. This property is not supported + by AD LDS. + - AllowReversiblePasswordEncryption - A property of type + System.Boolean, for AD DS it is derived from the directory + attribute: userAccountControl; for AD LDS it is derived from the + directory attribute: ms-DS-UserEncryptedTextPasswordAllowed + - BadLogonCount - A property of type System.Int32, derived from the + directory attribute: badPwdCount + - CannotChangePassword - A property of type System.Boolean, derived + from the directory attribute: nTSecurityDescriptor + - Certificates - A property of type + System.Security.Cryptography.X509Certificates.X509Certificate, + derived from the directory attribute: userCertificate + - DoesNotRequirePreAuth - A property of type System.Boolean, derived + from the directory attributes: userAccountControl, + msDS-User-Account-Control-Computed. This property is not supported + by AD LDS. + - Enabled - A property of type System.Boolean, for AD DS it is + derived from the directory attributes: userAccountControl, + msDS-User-Account-Control-Computed; for AD LDS it is derived from + the directory attribute msDS-UserAccountDisabled + - HomedirRequired - A property of type System.Boolean, derived from + the directory attributes: userAccountControl, + msDS-User-Account-Control-Computed. This property is not supported + by AD LDS. + - LastBadPasswordAttempt - A property of type System.DateTime, + derived from the directory attribute: badPasswordTime + - LastLogonDate - A property of type System.DateTime, derived from + the directory attribute: lastLogonTimestamp + - LockedOut - A property of type System.Boolean, for AD DS it is + derived from the directory attributes: userAccountControl, + msDS-User-Account-Control-Computed, lockoutTime; for AD LDS it is + derived from the directory attribute msDS-UserAccountDisabled + - MNSLogonAccount - A property of type System.Boolean, derived from + the directory attributes: userAccountControl, + msDS-User-Account-Control-Computed. This property is not supported + by AD LDS. + - PasswordExpired - A property of type System.Boolean, for AD DS it + is derived from the directory attributes: userAccountControl, + msDS-User-Account-Control-Computed; for AD LDS it is derived from + the directory attribute msDS-UserPasswordExpired + - PasswordLastSet - A property of type System.DateTime, derived from + the directory attribute: pwdLastSet + - PasswordNeverExpires - A property of type System.Boolean, for AD + LDS it is derived from the directory attributes: + userAccountControl, msDS-User-Account-Control-Computed; for AD LDS + it is derived from the directory attribute: + msDS-UserDontExpirePassword + - PasswordNotRequired - A property of type System.Boolean, for AD DS + it is derived from the directory attributes: userAccountControl, + msDS-User-Account-Control-Computed; for AD LDS it is derived from + the directory attribute: ms-DS-UserPasswordNotRequired + - PrimaryGroup - A property of type System.String, derived from the + directory attributes: primaryGroupID, objectSid. This property is + not supported by AD LDS. + - ServicePrincipalNames - A property of type System.String, derived + from the directory attribute: servicePrincipalName. This property + is not supported by AD LDS. + - TrustedForDelegation - A property of type System.Boolean, derived + from the directory attributes: userAccountControl, + msDS-User-Account-Control-Computed. This property is not supported + by AD LDS. + - TrustedToAuthForDelegation - A property of type System.Boolean, + derived from the directory attributes: userAccountControl, + msDS-User-Account-Control-Computed. This property is not supported + by AD LDS. + - UseDESKeyOnly - A property of type System.Boolean, derived from the + directory attributes: userAccountControl, + msDS-User-Account-Control-Computed. This property is not supported + by AD LDS. + - UserPrincipalName - A property of type System.String, derived from + the directory attribute: userPrincipalName + - ADComputer - Represents a computer and is derived from ADAccount. + An ADComputer may contain the following properties in addition to + those inherited from its parent. + - DNSHostName - A property of type System.String, derived from the + directory attribute: dNSHostName + - IPv4Address - A property of type System.String, derived from the + directory attribute: dNSHostName + - IPv6Address - A property of type System.String, derived from the + directory attribute: dNSHostName + - Location - A property of type System.String, derived from the + directory attribute: location + - ManagedBy - A property of type System.String, derived from the + directory attribute: managedBy + - OperatingSystem - A property of type System.String, derived from + the directory attribute: operatingSystem + - OperatingSystemHotfix - A property of type System.String, derived + from the directory attribute: operatingSystemHotfix + - OperatingSystemServicePack - A property of type System.String, + derived from the directory attribute: operatingSystemServicePack + - OperatingSystemVersion - A property of type System.String, + derived from the directory attribute: operatingSystemVersion + - ServiceAccount - A property of type System.String, derived from + the directory attribute: msDS-HostServiceAccount + - ADServiceAccount - Represents a managed service account; that is, + an Active Directory object of type msDS-ManagerdServiceAccount and + is derived from ADAccount. This class is not supported by AD LDS. + An ADServiceAccount may contain the following properties in + addition to those inherited from its parent. + - HostComputers - A property of type System.String, derived from + the directory attribute: msDS-HostServiceAccountBL + - ADUser - Represents a user (or iNetOrgPerson) and is derived from + ADAccount. An ADUser may contain the following properties in + addition to those inherited from its parent. + - City - A property of type System.String, derived from the + directory attribute: l + - Company - A property of type System.String, derived from the + directory attribute: company + - Country - A property of type System.String, derived from the + directory attribute: c + - Department - A property of type System.String, derived from the + directory attribute: department + - Division - A property of type System.String, derived from the + directory attribute: division + - EmailAddress - A property of type System.String, derived from the + directory attribute: mail + - EmployeeID - A property of type System.String, derived from the + directory attribute: employeeID + - EmployeeNumber - A property of type System.String, derived from + the directory attribute: employeeNumber + - Fax - A property of type System.String, derived from the + directory attribute: facsimileTelephoneNumber + - GivenName - A property of type System.String, derived from the + directory attribute: givenName + - HomeDirectory - A property of type System.String, derived from + the directory attribute: homeDirectory. This property is not + supported by AD LDS. + - HomeDrive - A property of type System.String, derived from the + directory attribute: homeDrive. This property is not supported by + AD LDS. + - HomePhone - A property of type System.String, derived from the + directory attribute: homePhone + - Initials - A property of type System.String, derived from the + directory attribute: initials + - LogonWorkstations - A property of type System.String, derived + from the directory attribute: userWorkstations. This property is + not supported by AD LDS. + - Manager - A property of type System.String, derived from the + directory attribute: manager + - MobilePhone - A property of type System.String, derived from the + directory attribute: mobile + - Office - A property of type System.String, derived from the + directory attribute: physicalDeliveryOfficeName + - OfficePhone - A property of type System.String, derived from the + directory attribute: telephoneNumber + - Organization - A property of type System.String, derived from the + directory attribute: o + - OtherName - A property of type System.String, derived from the + directory attribute: middleName + - POBox - A property of type System.String, derived from the + directory attribute: postOfficeBox + - PostalCode - A property of type System.String, derived from the + directory attribute: postalCode + - ProfilePath - A property of type System.String, derived from the + directory attribute: profilePath. This property is not supported + by AD LDS. + - ScriptPath - A property of type System.String, derived from the + directory attribute: scriptPath. This property is not supported + by AD LDS. + - SmartcardLogonRequired - A property of type System.Boolean, + derived from the directory attributes: userAccountControl, + msDS-User-Account-Control-Computed. This property is not + supported by AD LDS. + - State - A property of type System.String, derived from the + directory attribute: st + - StreetAddress - A property of type System.String, derived from + the directory attribute: streetAddress + - Surname - A property of type System.String, derived from the + directory attribute: sn + - Title - A property of type System.String, derived from the + directory attribute: title + - ADGroup -Represents a group and is derived from ADPrincipal. An + ADGroup may contain the following properties in addition to those + inherited from its parent. + - GroupCategory - A property of type + Microsoft.ActiveDirectory.Management.ADGroupCategory, derived from + the directory attribute: groupType + - GroupScope - A property of type + Microsoft.ActiveDirectory.Management.ADGroupScope, derived from the + directory attribute: groupType + - ManagedBy - A property of type System.String, derived from the + directory attribute: managedBy + - Members - A property of type System.String, derived from the + directory attribute: member + - ADDefaultDomainPasswordPolicy - Represents the domain-wide password policy + of an Active Directory domain and is derived from ADEntity. This class is + not supported by AD LDS. An ADDefaultDomainPasswordPolicy may contain the + following properties in addition to those inherited from its parent. + - ComplexityEnabled - A property of type System.Boolean, derived from the + directory attribute: pwdProperties + - DistinguishedName - A property of type System.String, derived from the + directory attribute: distinguishedName + - LockoutDuration - A property of type System.TimeSpan, derived from the + directory attribute: lockoutDuration + - LockoutObservationWindow - A property of type System.TimeSpan, derived + from the directory attribute: lockoutObservationWindow + - LockoutThreshold - A property of type System.Int32, derived from the + directory attribute: lockoutThreshold + - MaxPasswordAge - A property of type System.TimeSpan, derived from the + directory attribute: maxPwdAge + - MinPasswordAge - A property of type System.TimeSpan, derived from the + directory attribute: minPwdAge + - MinPasswordLength - A property of type System.Int32, derived from the + directory attribute: minPwdLength + - PasswordHistoryCount - A property of type System.Int32, derived from the + directory attribute: pwdHistoryLength + - ReversibleEncryptionEnabled - A property of type System.Boolean, derived + from the directory attribute: pwdProperties + - ADForest - Represents a Active Directory forest in AD DS or a Configuration + Set in AD LDS and is derived from ADEntity. This class is not supported by + AD LDS. An ADForest may contain the following properties in addition to + those inherited from its parent. + - ApplicationPartitions - A property of type System.String, derived from + the directory attribute: ApplicationPartitions + - CrossForestReferences - A property of type System.String, derived from + the directory attribute: CrossForestReferences + - DomainNamingMaster - A property of type System.String, derived from the + directory attribute: DomainNamingMaster + - Domains - A property of type System.String, derived from the directory + attribute: Domains + - ForestMode - A property of type System.Int32, derived from the directory + attribute: msDS-Behavior-Version + - GlobalCatalogs - A property of type System.String, derived from the + directory attribute: GlobalCatalogs + - Name - A property of type System.String, derived from the directory + attribute: name + - PartitionContainerName - A property of type System.String, derived from + the directory attribute: distinguishedName + - RootDomain - A property of type System.String, derived from the directory + attribute: RootDomain + - SchemaMaster - A property of type System.String, derived from the + directory attribute: SchemaMaster + - Sites - A property of type System.String, derived from the directory + attribute: Sites + - SPNSuffixes - A property of type System.String, derived from the + directory attribute: msDS-SPNSuffixes + - UPNSuffixes - A property of type System.String, derived from the + directory attribute: uPNSuffixes + - ADDirectoryServer - Represents a directory server used as either a domain + controller or an AD LDS instance and is derived from ADEntity. An + ADDirectoryServer may contain the following properties in addition to those + inherited from its parent. + - DefaultPartition - A property of type System.String, derived from the + directory attribute: DefaultPartition + - HostName - A property of type System.String, derived from the directory + attribute: HostName + - InvocationId - A property of type System.Guid, derived from the directory + attribute: InvocationId + - IPv4Address - A property of type System.String, derived from the + directory attribute: HostName + - IPv6Address - A property of type System.String, derived from the + directory attribute: HostName + - LdapPort - A property of type System.Int32, derived from the directory + attribute: LdapPort + - Name - A property of type System.String, derived from the directory + attribute: Name + - NTDSSettingsObjectDN - A property of type System.String, derived from the + directory attribute: NTDSSettingsObjectDN + - OperationMasterRoles - A property of type + Microsoft.ActiveDirectory.Management.ADOperationMasterRole, derived from + the directory attribute: OperationMasterRole + - Partitions - A property of type System.String, derived from the directory + attribute: Partitions + - ServerObjectDN - A property of type System.String, derived from the + directory attribute: ServerObjectDN + - ServerObjectGuid - A property of type System.Guid, derived from the + directory attribute: ServerObjectGuid + - Site - A property of type System.String, derived from the directory + attribute: Site + - SslPort - A property of type System.Int32, derived from the directory + attribute: SslPort + - ADDomainController - Represents a domain controller in AD DS and is + derived from ADDirectoryServer. An ADDomainController may contain the + following properties in addition to those inherited from its parent. + - ComputerObjectDN - A property of type System.String, derived from the + directory attribute: ComputerDN + - Domain - A property of type System.String, derived from the directory + attribute: Domain + - Enabled - A property of type System.Boolean, derived from the directory + attribute: Enabled + - Forest - A property of type System.String, derived from the directory + attribute: Forest + - IsGlobalCatalog - A property of type System.Boolean, derived from the + directory attribute: IsGlobalCatalog + - IsReadOnly - A property of type System.Boolean, derived from the + directory attribute: IsReadOnly + - OperatingSystem - A property of type System.String, derived from the + directory attribute: OSName + - OperatingSystemHotfix - A property of type System.String, derived from + the directory attribute: OSHotFix + - OperatingSystemServicePack - A property of type System.String, derived + from the directory attribute: OSServicepack + - OperatingSystemVersion - A property of type System.String, derived from + the directory attribute: OSVersion diff --git a/docset/winserver2025-ps/activedirectory/New-ADFineGrainedPasswordPolicy.md b/docset/winserver2025-ps/activedirectory/New-ADFineGrainedPasswordPolicy.md index 279660c38a..57aa2cef51 100644 --- a/docset/winserver2025-ps/activedirectory/New-ADFineGrainedPasswordPolicy.md +++ b/docset/winserver2025-ps/activedirectory/New-ADFineGrainedPasswordPolicy.md @@ -71,13 +71,6 @@ PS C:\> New-ADFineGrainedPasswordPolicy -Instance $TemplatePSO -Name "AdminsPSO" This example creates two new fine-grained password policy objects using a template object. -### Example 3: Create a fine-grained password policy with manual account unlock -```powershell -PS C:\> New-ADFineGrainedPasswordPolicy -Name "ManualUnlockPSO" -Precedence 500 -ComplexityEnabled $true -Description "Manual Unlock Password Policy" -DisplayName "Manual Unlock PSO" -LockoutDuration "00:00:00" -LockoutObservationWindow "00:00:00" -LockoutThreshold 3 -``` - -This command creates a fine-grained password policy object named ManualUnlockPSO that would require manual unlock of accounts by the administrator. - ## PARAMETERS ### -AuthType @@ -275,6 +268,10 @@ The LDAP display name (**ldapDisplayName**) of this property is **msDS-lockoutOb The lockout observation window must be smaller than or equal to the lockout duration for a password policy. Use the *LockoutDuration* parameter to set the lockout duration time. +> [!NOTE] +> Setting the lockout observation window to 0 effectively means that the window is too short to +> observe more than one password attempt, therefore the account will never be locked out. + Specify the time interval in the following format: `D:H:M:S.F` diff --git a/docset/winserver2025-ps/clusterawareupdating/Add-CauClusterRole.md b/docset/winserver2025-ps/clusterawareupdating/Add-CauClusterRole.md index 76b7ae0a82..e37893cc03 100644 --- a/docset/winserver2025-ps/clusterawareupdating/Add-CauClusterRole.md +++ b/docset/winserver2025-ps/clusterawareupdating/Add-CauClusterRole.md @@ -2,7 +2,7 @@ description: Use this topic to help manage Windows and Windows Server technologies with Windows PowerShell. external help file: ClusterAwareUpdating.dll-Help.xml Module Name: ClusterAwareUpdating -ms.date: 09/27/2022 +ms.date: 07/01/2024 online version: https://learn.microsoft.com/powershell/module/clusterawareupdating/add-cauclusterrole?view=windowsserver2025-ps&wt.mc_id=ps-gethelp schema: 2.0.0 title: Add-CauClusterRole @@ -23,10 +23,14 @@ Add-CauClusterRole [-VirtualComputerObjectName ] [-GroupName ] [-CauPluginName ] [-CauPluginArguments ] [-MaxFailedNodes ] [-MaxRetriesPerNode ] [-NodeOrder ] [-PreUpdateScript ] [-PostUpdateScript ] [-ConfigurationName ] [-RequireAllNodesOnline] - [-WarnAfter ] [-StopAfter ] [-RebootTimeoutMinutes ] [-SeparateReboots] - [-RunPluginsSerially] [-StopOnPluginFailure] [-EnableFirewallRules] [-FailbackMode ] - [-SuspendClusterNodeTimeoutMinutes ] [[-ClusterName] ] [[-Credential] ] - [-Force] [-WhatIf] [-Confirm] [] + [-WarnAfter ] [-StopAfter ] [-RebootTimeoutMinutes ] + [-SeparateReboots] [-RunPluginsSerially] [-StopOnPluginFailure] [-EnableFirewallRules] + [-FailbackMode ] [-SuspendClusterNodeTimeoutMinutes ] + [-SuspendRetriesPerNode ] [-WaitForStorageRepairTimeoutMinutes ] [-ForcePauseNoDrain] + [-ForcePauseAndDrain] [-ForcePauseDrainAndReboot] [-SkipUpdateChecks] + [-SiteAwareUpdatingOrder ] [-OsRollingUpgrade] [-AttemptSoftReboot] + [-RebootMode ] [[-ClusterName] ] [[-Credential] ] [-Force] + [-WhatIf] [-Confirm] [] ``` ### Weekly @@ -39,8 +43,27 @@ Add-CauClusterRole [-VirtualComputerObjectName ] [-GroupName ] [-PostUpdateScript ] [-ConfigurationName ] [-RequireAllNodesOnline] [-WarnAfter ] [-StopAfter ] [-RebootTimeoutMinutes ] [-SeparateReboots] [-RunPluginsSerially] [-StopOnPluginFailure] [-EnableFirewallRules] [-FailbackMode ] - [-SuspendClusterNodeTimeoutMinutes ] [[-ClusterName] ] [[-Credential] ] - [-Force] [-WhatIf] [-Confirm] [] + [-SuspendClusterNodeTimeoutMinutes ] [-SuspendRetriesPerNode ] + [-WaitForStorageRepairTimeoutMinutes ] [-ForcePauseNoDrain] [-ForcePauseAndDrain] + [-ForcePauseDrainAndReboot] [-SkipUpdateChecks] [-SiteAwareUpdatingOrder ] + [-OsRollingUpgrade] [-AttemptSoftReboot] [-RebootMode ] [[-ClusterName] ] + [[-Credential] ] [-Force] [-WhatIf] [-Confirm] [] +``` + +### Once + +``` +Add-CauClusterRole [-VirtualComputerObjectName ] [-GroupName ] [-RunOnce] + [-CauPluginName ] [-CauPluginArguments ] [-MaxFailedNodes ] + [-MaxRetriesPerNode ] [-NodeOrder ] [-PreUpdateScript ] + [-PostUpdateScript ] [-ConfigurationName ] [-RequireAllNodesOnline] + [-WarnAfter ] [-StopAfter ] [-RebootTimeoutMinutes ] [-SeparateReboots] + [-RunPluginsSerially] [-StopOnPluginFailure] [-EnableFirewallRules] [-FailbackMode ] + [-SuspendClusterNodeTimeoutMinutes ] [-SuspendRetriesPerNode ] + [-WaitForStorageRepairTimeoutMinutes ] [-ForcePauseNoDrain] [-ForcePauseAndDrain] + [-ForcePauseDrainAndReboot] [-SkipUpdateChecks] [-SiteAwareUpdatingOrder ] + [-OsRollingUpgrade] [-AttemptSoftReboot] [-RebootMode ] [[-ClusterName] ] + [[-Credential] ] [-Force] [-WhatIf] [-Confirm] [] ``` ## DESCRIPTION @@ -50,9 +73,9 @@ the self-updating functionality to the specified cluster. When the CAU clustered to a cluster, the failover cluster can update itself on the schedule that is specified by the user, without requiring an external computer to coordinate the cluster updating process. -To run this cmdlet, Windows PowerShell® remoting must be enabled on each node. To do this, run the -`Enable-PSRemoting` cmdlet. In addition, ensure that the Windows Remote Management - Compatibility -Mode (HTTP-In) firewall exception is enabled on each node. +To run this cmdlet, Windows PowerShell remoting must be enabled on each node. To do this, run the +`Enable-PSRemoting` cmdlet. In addition, ensure that the **Windows Remote Management - Compatibility +Mode (HTTP-In)** firewall exception is enabled on each node. ## EXAMPLES @@ -75,14 +98,14 @@ $parameters = @{ Add-CauClusterRole @parameters ``` -This command adds the CAU clustered role, using a default name, on the cluster called CONTOSO-FC1. -The CAU clustered role is configured to perform Updating Runs on Tuesdays and Saturdays on the -second and fourth weeks of each month. In an Updating Run, the maximum number of failed nodes is two -and the maximum number of retries per node is two. A script called verifyupdatesinstalled.ps1 runs -on each node after it has been fully updated. Before an Updating Run can begin, all the nodes of -that cluster must be running. If it isn't already enabled, the Remote Shutdown Windows Firewall -rule group will be enabled on each cluster node. Because the command uses the **Force** parameter, the -cmdlet runs without displaying confirmation prompts. +This command adds the CAU clustered role, using a default name, on the cluster called +**CONTOSO-FC1**. The CAU clustered role is configured to perform Updating Runs on Tuesdays and +Saturdays on the second and fourth weeks of each month. In an Updating Run, the maximum number of +failed nodes is two and the maximum number of retries per node is two. A script called +`verifyupdatesinstalled.ps1` runs on each node after it has been fully updated. Before an Updating +Run can begin, all the nodes of that cluster must be running. If it isn't already enabled, the +Remote Shutdown Windows Firewall rule group will be enabled on each cluster node. Because the +command uses the **Force** parameter, the cmdlet runs without displaying confirmation prompts. This example uses splatting to pass parameter values from the `$parameters` variable to the command. Learn more about [Splatting](/powershell/module/microsoft.powershell.core/about/about_splatting). @@ -103,14 +126,14 @@ $parameters = @{ Add-CauClusterRole @parameters ``` -This command adds the CAU clustered role, using a default name, on the cluster called CONTOSO-FC1. -The CAU clustered role is configured to perform Updating Runs on Tuesdays and Saturdays at an -interval of every three weeks. In an Updating Run, the maximum number of failed nodes is two and the -maximum number of retries per node is two. Updating Runs can begin even when the nodes of the -cluster aren't all running (if the cluster itself has quorum and is running). If it isn't already -enabled, the Remote Shutdown Windows Firewall rule group will be enabled on each cluster node. -Because the command uses the **Force** parameter, the cmdlet runs without displaying confirmation -prompts. +This command adds the CAU clustered role, using a default name, on the cluster called +**CONTOSO-FC1**. The CAU clustered role is configured to perform Updating Runs on Tuesdays and +Saturdays at an interval of every three weeks. In an Updating Run, the maximum number of failed +nodes is two and the maximum number of retries per node is two. Updating Runs can begin even when +the nodes of the cluster aren't all running (if the cluster itself has quorum and is running). If +it isn't already enabled, the Remote Shutdown Windows Firewall rule group will be enabled on each +cluster node. Because the command uses the **Force** parameter, the cmdlet runs without displaying +confirmation prompts. This example uses splatting to pass parameter values from the `$parameters` variable to the command. Learn more about [Splatting](/powershell/module/microsoft.powershell.core/about/about_splatting). @@ -131,36 +154,61 @@ $parameters = @{ Add-CauClusterRole @parameters ``` -This command adds the CAU clustered role, using a default name, on the cluster called CONTOSO-FC1. -The CAU clustered role is configured to perform updates using the **Microsoft.WindowsUpdatePlugin** -plug-in with the optional **IncludeRecommendedUpdates** parameter set to True, and using the -**Microsoft.HotfixPlugin plug-in** using the hotfix root folder `\\CauHotfixSrv\shareName` and the -default hotfix configuration file. If a failure occurs during the installation of updates on a node -by **Microsoft.WindowsUpdatePlugin**, updates are applied by **Microsoft.HotfixPlugin plug-in**. If -it isn't already enabled, the Remote Shutdown Windows Firewall rule group is enabled on each -cluster node. Because the command uses the **Force** parameter, the cmdlet runs without displaying -confirmation prompts. +This command adds the CAU clustered role, using a default name, on the cluster called +**CONTOSO-FC1**. The CAU clustered role is configured to perform updates using the +**Microsoft.WindowsUpdatePlugin** plug-in with the optional **IncludeRecommendedUpdates** parameter +set to `True`, and using the **Microsoft.HotfixPlugin plug-in** using the hotfix root folder +`\\CauHotfixSrv\shareName` and the default hotfix configuration file. If a failure occurs during +the installation of updates on a node by **Microsoft.WindowsUpdatePlugin**, updates are applied by +**Microsoft.HotfixPlugin plug-in**. If it isn't already enabled, the Remote Shutdown Windows +Firewall rule group is enabled on each cluster node. Because the command uses the **Force** +parameter, the cmdlet runs without displaying confirmation prompts. This example uses splatting to pass parameter values from the `$parameters` variable to the command. Learn more about [Splatting](/powershell/module/microsoft.powershell.core/about/about_splatting). ## PARAMETERS +### -AttemptSoftReboot + +Indicates that the CAU clustered role attempts a Kernel Soft Reboot (KSR) for the failover cluster. + +KSR bypasses BIOS/firmware initialization. You can only use KSR for updates that do not require a +BIOS/firmware initialization. + +```yaml +Type: SwitchParameter +Parameter Sets: (All) +Aliases: + +Required: False +Position: Named +Default value: None +Accept pipeline input: False +Accept wildcard characters: False +``` + ### -CauPluginArguments -Specifies an array of name=value pairs (arguments) for each updating plug-in to use. +Specifies a set of name=value pairs, as arguments, for each updating plug-in to use. + For instance, to specify a Domain argument for one plug-in: + - `@{Domain=Domain.local}` -You can specify multiple pairs in a set separated with semicolons. -For instance: -- `@{name1=value1;name2=value2;name3=value3}` These name=value pairs must be meaningful to the - **CauPluginName** parameter that you specify. If you specify arguments for more than one plug-in, - provide the sets of name=value pairs in the order that you pass values in **CauPluginName**, - separated by commas. For instance: + +You can specify multiple pairs in a set separated with semicolons. For instance: + +- `@{name1=value1;name2=value2;name3=value3}` + +These name=value pairs must be meaningful to the **CauPluginName** parameter that you specify. If +you specify arguments for more than one plug-in, provide the sets of name=value pairs in the order +that you pass values in **CauPluginName**, separated by commas. For instance: + - `@{name1=value1;name2=value2;name3=value3},@{name4=value4;name5=value5}` -For the default **Microsoft.WindowsUpdatePlugin** plug-in, no arguments are needed. -The following arguments are optional: +For the default **Microsoft.WindowsUpdatePlugin** plug-in, no arguments are needed. The following +arguments are optional: + - **'IncludeRecommendedUpdates'='\'**: Boolean value to indicate that recommended updates will be applied in addition to important updates on each node. If not specified, the default value is False. @@ -168,30 +216,32 @@ The following arguments are optional: Agent to filter the updates that will be applied to each node. For a name, use **QueryString** and for a value, enclose the full query in quotation marks. If not specified, then the **Microsoft.WindowsUpdatePlugin** plug-in by default uses the following argument: -- `QueryString="IsInstalled=0 and Type='Software' and IsHidden=0 and IsAssigned=1"` For more - information about query strings for the default **Microsoft.WindowsUpdatePlugin** plug-in and the - criteria such as IsInstalled that can be included in the query strings, see - [IUpdateSearcher::Search method](https://go.microsoft.com/fwlink/p/?LinkId=223304). +- `QueryString="IsInstalled=0 and Type='Software' and IsHidden=0 and IsAssigned=1"` + +For more information about query strings for the default **Microsoft.WindowsUpdatePlugin** plug-in +and the criteria such as IsInstalled that can be included in the query strings, see +[IUpdateSearcher::Search method](/windows/win32/api/wuapi/nf-wuapi-iupdatesearcher-search). + +For the **Microsoft.HotfixPlugin** plug-in, the following argument is required: -For the **Microsoft.HotfixPlugin** plug-in. -the following argument is required: - **HotfixRootFolderPath=\**: The UNC path to a hotfix root folder in an SMB share with a - structure that contains the updates to apply and that contains the hotfix configuration file + structure that contains the updates to apply and that contains the hotfix configuration file. The following arguments are optional for the **Microsoft.HotfixPlugin** plug-in: + - **RequireSmbEncryption=\**: Boolean value to indicate that SMB Encryption will be enforced for accessing data from the SMB share. If not specified, the default value is False. To ensure the integrity of the data accessed from the SMB share, the plug-in requires that the share is enabled for either SMB signing or SMB Encryption. -- **DisableAclChecks=\**: Boolean value to indicate that the plug-in checks for sufficient - permissions on the hotfix root folder and the hotfix configuration file. If not specified, the - default value is False. +- **DisableAclChecks=\**: Boolean value to indicate that the plug-in will check for + sufficient permissions on the hotfix root folder and the hotfix configuration file. If not + specified, the default value is False. - **HotfixInstallerTimeoutMinutes=\**: The length of time in minutes that the plug-in allows the hotfix installer process to return. If not specified, the default value is 30 minutes. - **HotfixConfigFileName=\**: Name for the hotfix configuration file. If not specified, the - default name DefaultHotfixConfigFile.xml is used. For more information about required and optional + default name `DefaultHotfixConfig.xml` is used. For more information about required and optional arguments for the **Microsoft.HotfixPlugin** plug-in, see - [How CAU Plug-ins Work](https://go.microsoft.com/fwlink/p/?LinkId=235333). + [How Cluster-Aware Updating plug-ins work](/windows-server/failover-clustering/cluster-aware-updating-plug-ins). ```yaml Type: Hashtable[] @@ -208,11 +258,12 @@ Accept wildcard characters: False ### -CauPluginName Specifies one or more plug-ins to use when performing scans or updates. You can specify multiple -values separated with commas. The default is the Microsoft.WindowsUpdatePlugin plug-in. This plug-in -coordinates the Windows Update Agent software resident on each cluster node, the same software that -is used when updates are downloaded from Windows Update or Microsoft Update, or from a Windows -Server Update Services (WSUS) server. For more information about how plug-ins work with CAU, see -[How CAU Plug-ins Work](https://go.microsoft.com/fwlink/p/?LinkId=235333). +values separated with commas. The default is the **Microsoft.WindowsUpdatePlugin** plug-in. This +plug-in coordinates the Windows Update Agent software resident on each cluster node, the same +software that is used when updates are downloaded from Windows Update or Microsoft Update, or from +a Windows Server Update Services (WSUS) server. For more information about how plug-ins work with +CAU, see +[How Cluster-Aware Updating plug-ins work](/windows-server/failover-clustering/cluster-aware-updating-plug-ins). ```yaml Type: String[] @@ -247,10 +298,10 @@ Accept wildcard characters: False ### -ConfigurationName Specifies the Windows PowerShell session configuration that defines the session in which scripts, -specified by the **PreUpdateScript** and **PostUpdateScript** parameters, and cmdlets are run, and can -limit the cmdlets that are available to be run. If either a pre-update or post-update script is +specified by the **PreUpdateScript** and **PostUpdateScript** parameters, and cmdlets are run, and +can limit the cmdlets that are available to be run. If either a pre-update or post-update script is specified but a configuration name isn't specified, then the default session configuration that is -built into Windows PowerShell® is used. +built into Windows PowerShell is used. ```yaml Type: String @@ -264,22 +315,6 @@ Accept pipeline input: False Accept wildcard characters: False ``` -### -Confirm - -Prompts you for confirmation before running the cmdlet. - -```yaml -Type: SwitchParameter -Parameter Sets: (All) -Aliases: cf - -Required: False -Position: Named -Default value: False -Accept pipeline input: False -Accept wildcard characters: False -``` - ### -Credential Specifies the administrative credentials for the target cluster. @@ -298,8 +333,8 @@ Accept wildcard characters: False ### -DaysOfWeek -Specifies the days of the week on which the updating task will be triggered. -Multiple values can be specified either separated with commas or as a hexadecimal sum. +Specifies the days of the week on which the updating task will be triggered. Multiple values can be +specified either separated with commas or as a hexadecimal sum. The acceptable values for this parameter are: @@ -313,7 +348,7 @@ The acceptable values for this parameter are: ```yaml Type: Weekdays -Parameter Sets: (All) +Parameter Sets: MonthlyDayOfWeek, Weekly Aliases: Accepted values: None, Sunday, Monday, Tuesday, Wednesday, Thursday, Friday, Saturday @@ -326,15 +361,17 @@ Accept wildcard characters: False ### -EnableFirewallRules -Indicates that the cmdlet enables the Remote Shutdown Windows Firewall rule group on each cluster -node, if it isn't already enabled. If the **EnableFirewallRules** parameter is specified, CAU will -also automatically re-enable the Remote Shutdown rule group each time the CAU clustered role -performs an Updating Run, in case the rules are disabled manually in the intervening time. Enabling -this rule group permits inbound communication to each cluster node during each Updating Run that -allows CAU to shut down and restart the node remotely (if the installation of an update requires a -restart). If Windows Firewall is in use on the cluster nodes and the rule group isn't enabled, the -Updating Run will fail. The Remote Shutdown Windows Firewall rule group isn't enabled when it will -conflict with Group Policy settings that are configured for Windows Firewall. +Indicates that the cmdlet enables the **Remote Shutdown** Windows Firewall rule group on each +cluster node, if it isn't already enabled. If the **EnableFirewallRules** parameter is specified, +CAU will also automatically re-enable the **Remote Shutdown** rule group each time the CAU +clustered role performs an Updating Run, in case the rules are disabled manually in the intervening +time. + +Enabling this rule group permits inbound communication to each cluster node during each Updating +Run that allows CAU to shut down and restart the node remotely (if the installation of an update +requires a restart). If Windows Firewall is in use on the cluster nodes and the rule group isn't +enabled, the Updating Run will fail. The Remote Shutdown Windows Firewall rule group isn't enabled +when it will conflict with Group Policy settings that are configured for Windows Firewall. ```yaml Type: SwitchParameter @@ -356,11 +393,11 @@ another node. The acceptable values for this parameter are: -- NoFailback -- Immediate -- Policy +- `NoFailback` +- `Immediate` +- `Policy` -The default value is Immediate. +The default value is **Immediate**. ```yaml Type: FailbackType @@ -391,6 +428,60 @@ Accept pipeline input: False Accept wildcard characters: False ``` +### -ForcePauseAndDrain + +Indicates that the CAU cluster role forces cluster nodes to pause and drain roles. + +A forced drain moves the roles off of the draining node even if the group cannot move. A group +might not be able to move because no other node can host the group or the group is locked. + +```yaml +Type: SwitchParameter +Parameter Sets: (All) +Aliases: + +Required: False +Position: Named +Default value: None +Accept pipeline input: False +Accept wildcard characters: False +``` + +### -ForcePauseDrainAndReboot + +Indicates that the CAU cluster role forces cluster nodes to pause, drain roles, and restart. + +A forced drain moves the roles off of the draining node even if the group cannot move. A group +might not be able to move because no other node can host the group or the group is locked. + +```yaml +Type: SwitchParameter +Parameter Sets: (All) +Aliases: + +Required: False +Position: Named +Default value: None +Accept pipeline input: False +Accept wildcard characters: False +``` + +### -ForcePauseNoDrain + +Indicates that the CAU cluster role forces cluster nodes to pause. The nodes are not drained. + +```yaml +Type: SwitchParameter +Parameter Sets: (All) +Aliases: + +Required: False +Position: Named +Default value: None +Accept pipeline input: False +Accept wildcard characters: False +``` + ### -GroupName Specifies the NetBIOS name of the resource group for the CAU clustered role. @@ -409,9 +500,8 @@ Accept wildcard characters: False ### -IntervalWeeks -Specifies the interval between weeks when the task will be triggered. -An interval of 1 produces a weekly schedule. -An interval of 2 produces an every-other week schedule. +Specifies the interval between weeks when the task will be triggered. An interval of 1 produces a +weekly schedule. An interval of 2 produces an every-other week schedule. ```yaml Type: Int32 @@ -427,10 +517,9 @@ Accept wildcard characters: False ### -MaxFailedNodes -Specifies the maximum number of nodes on which updating can fail. -If one more than this number of nodes fails, then the Updating Run is stopped. -The range is from 0 through 1, less than the number of cluster nodes. -The default for most clusters is approximately one-third of the number of nodes. +Specifies the maximum number of nodes on which updating can fail. If one more than this number of +nodes fails, then the Updating Run is stopped. The range is from 0 through 1, less than the number +of cluster nodes. The default for most clusters is approximately one-third of the number of nodes. ```yaml Type: Int32 @@ -446,10 +535,9 @@ Accept wildcard characters: False ### -MaxRetriesPerNode -Specifies the maximum number of times that the update process attempts to run. -This includes any pre-update and post-update scripts. -The update process is retried per node. -The maximum is 64 and the default is 3. +Specifies the maximum number of times that the update process attempts to run. This includes any +pre-update and post-update scripts. The update process is retried per node. The maximum is 64 +and the default is 3. ```yaml Type: Int32 @@ -479,11 +567,28 @@ Accept pipeline input: False Accept wildcard characters: False ``` +### -OsRollingUpgrade + +Indicates that the CAU cluster role upgrades the operating system of the cluster nodes without +stopping the Hyper-V or the Scale-Out File Server workloads. + +```yaml +Type: SwitchParameter +Parameter Sets: (All) +Aliases: + +Required: False +Position: Named +Default value: None +Accept pipeline input: False +Accept wildcard characters: False +``` + ### -PostUpdateScript Specifies the path and file name for a Windows PowerShell script to run on each node after updating finishes, and just after the node is brought out of Maintenance mode. The file name extension must -be .ps1 and the total length of the path plus the file name must be no longer than 260 characters. +be `.ps1` and the total length of the path plus the file name must be no longer than 260 characters. As a best practice, the script should be located on a disk in cluster storage, or at a highly available network share, to ensure that the script is always accessible to all the cluster nodes. @@ -502,7 +607,7 @@ Accept wildcard characters: False ### -PreUpdateScript Specifies the path and file name for a Windows PowerShell script to run on each node before updating -begins, and before the node is put into Maintenance mode. The file name extension must be .ps1 and +begins, and before the node is put into Maintenance mode. The file name extension must be `.ps1` and the total length of the path plus the file name must be no longer than 260 characters. As a best practice, the script should be located on a disk in cluster storage, or at a highly available network share, to ensure that the script is always accessible to all the cluster nodes. If a @@ -520,6 +625,30 @@ Accept pipeline input: False Accept wildcard characters: False ``` +### -RebootMode + +Specifies the type of reboot to use for each node in the cluster during the update. The available +values are: + +- `ClusProp` +- `FullReboot` +- `SoftReboot` +- `PluginCustomReboot` +- `OrchestratorDefault` + +```yaml +Type: RebootType +Parameter Sets: (All) +Aliases: +Accepted values: ClusProp, FullReboot, SoftReboot, PluginCustomReboot, OrchestratorDefault + +Required: False +Position: Named +Default value: None +Accept pipeline input: False +Accept wildcard characters: False +``` + ### -RebootTimeoutMinutes Specifies the time in minutes that CAU allows for the restarting of a node. If the restart doesn't @@ -554,6 +683,23 @@ Accept pipeline input: False Accept wildcard characters: False ``` +### -RunOnce + +Specifies that the CAU run should only be performed once, rather than on a recurring schedule. This +can be useful if you only need to perform a one-time update of your cluster nodes. + +```yaml +Type: SwitchParameter +Parameter Sets: Once +Aliases: + +Required: False +Position: Named +Default value: None +Accept pipeline input: False +Accept wildcard characters: False +``` + ### -RunPluginsSerially Indicates that the cmdlet CAU scans each cluster node for applicable updates and stages the updates @@ -599,13 +745,47 @@ Accept pipeline input: False Accept wildcard characters: False ``` +### -SiteAwareUpdatingOrder + +Specifies the order in which the CAU cluster role updates cluster nodes. + +By default, CAU selects the order of nodes to update based on the level of activity. + +```yaml +Type: String[] +Parameter Sets: (All) +Aliases: + +Required: False +Position: Named +Default value: None +Accept pipeline input: False +Accept wildcard characters: False +``` + +### -SkipUpdateChecks + +Indicates that the CAU cluster role skips update checks. + +```yaml +Type: SwitchParameter +Parameter Sets: (All) +Aliases: + +Required: False +Position: Named +Default value: None +Accept pipeline input: False +Accept wildcard characters: False +``` + ### -StartDate Specifies the earliest date on which the Updating Run can be triggered. ```yaml Type: DateTime -Parameter Sets: (All) +Parameter Sets: MonthlyDayOfWeek, Weekly Aliases: Required: False @@ -640,9 +820,10 @@ Accept wildcard characters: False ### -StopOnPluginFailure Indicates that this cmdlet coordinates subsequent updates on the node when plug-ins are stopped. -When multiple plug-ins are used during an updating run, by default, a failure by one plug-in doesn't affect the application of updates on a node by other plug-ins. This parameter is valid only when -multiple plug-ins are specified in the **CauPluginName** parameter. If a single plug-in is specified, -a warning appears. +When multiple plug-ins are used during an updating run, by default, a failure by one plug-in +doesn't affect the application of updates on a node by other plug-ins. This parameter is valid only +when multiple plug-ins are specified in the **CauPluginName** parameter. If a single plug-in is +specified, a warning appears. ```yaml Type: SwitchParameter @@ -662,8 +843,8 @@ Specifies the maximum amount of time CAU should wait for the `Suspend-ClusterNod succeed if the underlying clustered space is in degraded condition. If `Suspend-ClusterNode` fails with ERROR_CLUSTER_SPACE_DEGRADED error, CAU will keep retrying for -**SuspendClusterNodeTimeoutMinutes** or suspend the call if the command succeeds. The retries for this -error don't count towards the **MaxRetriesPerNode** parameter set by the user. +**SuspendClusterNodeTimeoutMinutes** or suspend the call if the command succeeds. The retries for +this error don't count towards the **MaxRetriesPerNode** parameter set by the user. The timeout value is per cluster node. So CAU could potentially spend the amount of time specified for this value for every node in the cluster in the worst case. @@ -680,11 +861,27 @@ Accept pipeline input: False Accept wildcard characters: False ``` +### -SuspendRetriesPerNode + +Specifies the number of times to retry suspending a node before moving on to the next node. + +```yaml +Type: Int32 +Parameter Sets: (All) +Aliases: + +Required: False +Position: Named +Default value: None +Accept pipeline input: False +Accept wildcard characters: False +``` + ### -VirtualComputerObjectName Specifies the name of a pre-staged virtual computer object that is used by the CAU clustered role. For more information, see -[Steps to create computer objects in Active Directory](https://go.microsoft.com/fwlink/p/?LinkId=237624). +[Steps for prestaging the cluster name account](/windows-server/failover-clustering/configure-ad-accounts#steps-for-prestaging-the-cluster-name-account). If not specified, then a virtual computer object is created using a generated name. Generating a name automatically requires the cluster name object to have permissions to create the virtual computer object in Active Directory. @@ -701,6 +898,23 @@ Accept pipeline input: False Accept wildcard characters: False ``` +### -WaitForStorageRepairTimeoutMinutes + +Specifies the amount of time in minutes to wait for storage to be repaired on a node before +continuing with an update. + +```yaml +Type: Int32 +Parameter Sets: (All) +Aliases: + +Required: False +Position: Named +Default value: None +Accept pipeline input: False +Accept wildcard characters: False +``` + ### -WarnAfter Specifies the time in minutes after which a warning will be logged if the Updating Run (including @@ -721,8 +935,8 @@ Accept wildcard characters: False ### -WeeksOfMonth -Specifies the weeks of the month when the Updating Run should be run. -The value `5` represents the last week of the month. +Specifies the weeks of the month when the Updating Run should be run. The value 5 represents the +last week of the month. ```yaml Type: Int32[] @@ -736,10 +950,25 @@ Accept pipeline input: False Accept wildcard characters: False ``` +### -Confirm + +Prompts you for confirmation before running the cmdlet. + +```yaml +Type: SwitchParameter +Parameter Sets: (All) +Aliases: cf + +Required: False +Position: Named +Default value: None +Accept pipeline input: False +Accept wildcard characters: False +``` + ### -WhatIf -Shows what would happen if the cmdlet runs. -The cmdlet isn't run. +Shows what would happen if the cmdlet runs. The cmdlet is not run. ```yaml Type: SwitchParameter @@ -748,7 +977,7 @@ Aliases: wi Required: False Position: Named -Default value: False +Default value: None Accept pipeline input: False Accept wildcard characters: False ``` @@ -758,7 +987,7 @@ Accept wildcard characters: False This cmdlet supports the common parameters: -Debug, -ErrorAction, -ErrorVariable, -InformationAction, -InformationVariable, -OutVariable, -OutBuffer, -PipelineVariable, -Verbose, -WarningAction, and -WarningVariable. For more information, see -[about_CommonParameters](https://go.microsoft.com/fwlink/?LinkID=113216). +[about_CommonParameters](/powershell/module/microsoft.powershell.core/about/about_commonparameters). ## INPUTS @@ -766,19 +995,18 @@ This cmdlet supports the common parameters: -Debug, -ErrorAction, -ErrorVariable ## OUTPUTS -### None +### System.Object ## NOTES ## RELATED LINKS -[Disable-CauClusterRole](./Disable-CauClusterRole.md) - -[Enable-CauClusterRole](./Enable-CauClusterRole.md) +[Disable-CauClusterRole](disable-cauclusterrole.md) -[Get-CauClusterRole](./Get-CauClusterRole.md) +[Enable-CauClusterRole](enable-cauclusterrole.md) -[Remove-CauClusterRole](./Remove-CauClusterRole.md) +[Get-CauClusterRole](get-cauclusterrole.md) -[Set-CauClusterRole](./Set-CauClusterRole.md) +[Remove-CauClusterRole](remove-cauclusterrole.md) +[Set-CauClusterRole](set-cauclusterrole.md) diff --git a/docset/winserver2025-ps/clusterawareupdating/Get-CauDeviceInfoForFeatureUpdates.md b/docset/winserver2025-ps/clusterawareupdating/Get-CauDeviceInfoForFeatureUpdates.md new file mode 100644 index 0000000000..7705540fcf --- /dev/null +++ b/docset/winserver2025-ps/clusterawareupdating/Get-CauDeviceInfoForFeatureUpdates.md @@ -0,0 +1,133 @@ +--- +description: Use this topic to help manage Windows and Windows Server technologies with Windows PowerShell. +external help file: ClusterAwareUpdating.dll-Help.xml +Module Name: ClusterAwareUpdating +ms.date: 07/01/2024 +online version: https://learn.microsoft.com/powershell/module/clusterawareupdating/get-caudeviceinfoforfeatureupdates?view=windowsserver2025-ps&wt.mc_id=ps-gethelp +schema: 2.0.0 +title: Get-CauDeviceInfoForFeatureUpdates +--- + +# Get-CauDeviceInfoForFeatureUpdates + +## SYNOPSIS +Retrieves device information for feature updates from a specified directory. + +## SYNTAX + +``` +Get-CauDeviceInfoForFeatureUpdates [[-ClusterName] ] [-Credential ] + -PathToDirectory [-PathToDeploymentCab ] [] +``` + +## DESCRIPTION + +The `Get-CauDeviceInfoForFeatureUpdates` cmdlet retrieves device information for feature updates +from a specified directory. + +## EXAMPLES + +### Example 1 + +```powershell +$parameters = @{ +ClusterName = "CONTOSO-FC1" +PathToDirectory = "C:\Updates" +PathToDeploymentCab = "C:\Deployment\FeatureUpdate.cab" +} +Get-CauDeviceInfoForFeatureUpdates $parameters +``` + +This command retrieves device information for feature updates from the `C:\Updates` directory for +the cluster named **CONTOSO-FC1**. It also specifies the path to the deployment cab file that will +be created for the update in `C:\Deployment\FeatureUpdate.cab`. + +## PARAMETERS + +### -ClusterName + +Specifies the name of the cluster on which to create the CAU clustered role. This parameter is only +required when this cmdlet isn't run on a failover cluster node, or this cmdlet is used to reference +a failover cluster different from where the cmdlet is run. + +```yaml +Type: String +Parameter Sets: (All) +Aliases: + +Required: False +Position: 0 +Default value: None +Accept pipeline input: False +Accept wildcard characters: False +``` + +### -Credential + +Specifies the administrative credentials for the target cluster. + +```yaml +Type: PSCredential +Parameter Sets: (All) +Aliases: + +Required: False +Position: Named +Default value: None +Accept pipeline input: False +Accept wildcard characters: False +``` + +### -PathToDeploymentCab + +Specifies the path to the deployment cab file that will be created for the update. + +```yaml +Type: String +Parameter Sets: (All) +Aliases: + +Required: False +Position: Named +Default value: None +Accept pipeline input: False +Accept wildcard characters: False +``` + +### -PathToDirectory + +Specifies the path to the directory that contains the device information files. This parameter is +required. + +```yaml +Type: String +Parameter Sets: (All) +Aliases: + +Required: True +Position: Named +Default value: None +Accept pipeline input: False +Accept wildcard characters: False +``` + +### CommonParameters + +This cmdlet supports the common parameters: -Debug, -ErrorAction, -ErrorVariable, +-InformationAction, -InformationVariable, -OutVariable, -OutBuffer, -PipelineVariable, -Verbose, +-WarningAction, and -WarningVariable. For more information, see +[about_CommonParameters](/powershell/module/microsoft.powershell.core/about/about_commonparameters). + +## INPUTS + +### None + +## OUTPUTS + +### System.String + +### Microsoft.ClusterAwareUpdating.ActivityIdMap + +## NOTES + +## RELATED LINKS diff --git a/docset/winserver2025-ps/clusterawareupdating/Get-ClusterlessCauRun.md b/docset/winserver2025-ps/clusterawareupdating/Get-ClusterlessCauRun.md new file mode 100644 index 0000000000..4f2abaeaf9 --- /dev/null +++ b/docset/winserver2025-ps/clusterawareupdating/Get-ClusterlessCauRun.md @@ -0,0 +1,103 @@ +--- +description: Use this topic to help manage Windows and Windows Server technologies with Windows PowerShell. +external help file: ClusterAwareUpdating.dll-Help.xml +Module Name: ClusterAwareUpdating +ms.date: 07/01/2024 +online version: https://learn.microsoft.com/powershell/module/clusterawareupdating/get-clusterlesscaurun?view=windowsserver2025-ps&wt.mc_id=ps-gethelp +schema: 2.0.0 +title: Get-ClusterlessCauRun +--- + +# Get-ClusterlessCauRun + +## SYNOPSIS +Retrieves information about a Cluster-Aware Updating (CAU) run not associated with a cluster. + +## SYNTAX + +### DefaultParamSet (Default) + +``` +Get-ClusterlessCauRun [-Credential ] [] +``` + +### ShowClusterNodeState + +``` +Get-ClusterlessCauRun [-Credential ] [-ShowClusterNodeState] [] +``` + +## DESCRIPTION + +The `Get-ClusterlessCauRun` cmdlet retrieves information about a Cluster-Aware Updating (CAU) run +that is not associated with a cluster. + +## EXAMPLES + +### Example 1 + +```powershell +Get-ClusterlessCauRun +``` + +This example displays information about the current CAU run, including the status of each node that +is being updated. + +## PARAMETERS + +### -Credential + +Specifies the administrative credentials for the target cluster. + +```yaml +Type: PSCredential +Parameter Sets: (All) +Aliases: + +Required: False +Position: Named +Default value: None +Accept pipeline input: False +Accept wildcard characters: False +``` + +### -ShowClusterNodeState + +Displays detailed information about the state of each node in the CAU run. + +```yaml +Type: SwitchParameter +Parameter Sets: ShowClusterNodeState +Aliases: + +Required: False +Position: Named +Default value: None +Accept pipeline input: False +Accept wildcard characters: False +``` + +### CommonParameters + +This cmdlet supports the common parameters: -Debug, -ErrorAction, -ErrorVariable, +-InformationAction, -InformationVariable, -OutVariable, -OutBuffer, -PipelineVariable, -Verbose, +-WarningAction, and -WarningVariable. For more information, see +[about_CommonParameters](/powershell/module/microsoft.powershell.core/about/about_commonparameters). + +## INPUTS + +### None + +## OUTPUTS + +### Microsoft.ClusterAwareUpdating.CauWmiObject + +### Microsoft.ClusterAwareUpdating.ClusterlessCauRun + +### Microsoft.ClusterAwareUpdating.RunState + +## NOTES + +## RELATED LINKS + +[Invoke-ClusterlessCauRun](invoke-clusterlesscaurun.md) diff --git a/docset/winserver2025-ps/clusterawareupdating/Invoke-CauRun.md b/docset/winserver2025-ps/clusterawareupdating/Invoke-CauRun.md index 6a185b4894..1b44570c08 100644 --- a/docset/winserver2025-ps/clusterawareupdating/Invoke-CauRun.md +++ b/docset/winserver2025-ps/clusterawareupdating/Invoke-CauRun.md @@ -2,7 +2,7 @@ description: Use this topic to help manage Windows and Windows Server technologies with Windows PowerShell. external help file: ClusterAwareUpdating.dll-Help.xml Module Name: ClusterAwareUpdating -ms.date: 09/27/2022 +ms.date: 07/01/2024 online version: https://learn.microsoft.com/powershell/module/clusterawareupdating/invoke-caurun?view=windowsserver2025-ps&wt.mc_id=ps-gethelp schema: 2.0.0 title: Invoke-CauRun @@ -11,7 +11,7 @@ title: Invoke-CauRun # Invoke-CauRun ## SYNOPSIS -Performs a scan of cluster nodes for applicable updates and installs those updates through an updating run on the specified cluster. +Performs a scan of cluster nodes for applicable updates and installs those updates through an Updating Run on the specified cluster. ## SYNTAX @@ -22,41 +22,62 @@ Invoke-CauRun [-MaxFailedNodes ] [-MaxRetriesPerNode ] [-NodeOrder [-PreUpdateScript ] [-PostUpdateScript ] [-ConfigurationName ] [-RequireAllNodesOnline] [-WarnAfter ] [-StopAfter ] [-RebootTimeoutMinutes ] [-SeparateReboots] [-EnableFirewallRules] - [-FailbackMode ] [-SuspendClusterNodeTimeoutMinutes ] [-Force] [[-ClusterName] -] [[-CauPluginName] ] [[-Credential] ] - [-CauPluginArguments ] [-RunPluginsSerially] [-StopOnPluginFailure] [-WhatIf] - [-Confirm] [] + [-FailbackMode ] [-SuspendClusterNodeTimeoutMinutes ] + [-SuspendRetriesPerNode ] [-WaitForStorageRepairTimeoutMinutes ] [-Force] + [-ForcePauseNoDrain] [-ForcePauseAndDrain] [-ForcePauseDrainAndReboot] [-SkipUpdateChecks] + [-ForceSelfUpdate] [-SiteAwareUpdatingOrder ] [[-ClusterName] ] + [-AttemptSoftReboot] [-CauPluginName ] [-Credential ] + [-CauPluginArguments ] [-RunPluginsSerially] [-StopOnPluginFailure] + [-OsRollingUpgrade] [-RebootMode ] [-WhatIf] [-Confirm] [] ``` ### RecoverParamSet ``` -Invoke-CauRun [-ForceRecovery] [-Force] [[-ClusterName] ] [[-Credential] ] - [-WhatIf] [-Confirm] [] +Invoke-CauRun [-ForceRecovery] [-ClearCorruptReports] [-Force] [-ForcePauseNoDrain] + [-ForcePauseAndDrain] [-ForcePauseDrainAndReboot] [-SkipUpdateChecks] [-ForceSelfUpdate] + [[-ClusterName] ] [-Credential ] [-WhatIf] [-Confirm] [] +``` + +### SuspendNodeParamSet + +``` +Invoke-CauRun -SuspendNode [-Force] [-ForcePauseNoDrain] [-ForcePauseAndDrain] + [-ForcePauseDrainAndReboot] [-SkipUpdateChecks] [-ForceSelfUpdate] [[-ClusterName] ] + [-Credential ] [-WhatIf] [-Confirm] [] +``` + +### ResumeNodeParamSet + +``` +Invoke-CauRun -ResumeNode [-Force] [-ForcePauseNoDrain] [-ForcePauseAndDrain] + [-ForcePauseDrainAndReboot] [-SkipUpdateChecks] [-ForceSelfUpdate] [[-ClusterName] ] + [-Credential ] [-WhatIf] [-Confirm] [] ``` ## DESCRIPTION The `Invoke-CauRun` cmdlet performs a scan of cluster nodes for applicable updates and installs -those updates through an updating run on the specified cluster. The updating run process includes +those updates through an Updating Run on the specified cluster. The Updating Run process includes the following: + - Scanning for and downloading applicable updates on each cluster node. - Moving currently running clustered roles off each cluster node. - Installing the updates on each cluster node. - Restarting cluster nodes if required by the installed updates. - Moving the clustered roles back to the original nodes. -- The updating run process also includes ensuring that quorum is maintained, checking for additional +- The Updating Run process also includes ensuring that quorum is maintained, checking for additional updates that can only be installed after the initial set of updates are installed, and saving a report of the actions taken. -To run this cmdlet with the **PostUpdateScript** or **PreUpdateScript** parameter, Windows PowerShell -remoting must be enabled on each node. To do this, run the `Enable-PSRemoting` cmdlet. In -addition, ensure that the **Windows Remote Management - Compatibility Mode (HTTP-In)** firewall +To run this cmdlet with the **PostUpdateScript** or **PreUpdateScript** parameter, Windows +PowerShell remoting must be enabled on each node. To do this, run the `Enable-PSRemoting` cmdlet. +In addition, ensure that the **Windows Remote Management - Compatibility Mode (HTTP-In)** firewall exception is enabled on each node. ## EXAMPLES -### Example 1: Preform a scan and a full updating run on the specified cluster +### Example 1: Perform a scan and a full Updating Run on the specified cluster ```powershell $parameters = @{ @@ -70,17 +91,17 @@ $parameters = @{ Invoke-CauRun @parameters ``` -This command performs a scan and a full updating run on the cluster named CONTOSO-FC1. This cmdlet -uses the **Microsoft.WindowsUpdatePlugin** plug-in and requires that all cluster nodes be online -before the running this cmdlet. In addition, this cmdlet allows no more than three retries per node -before marking the node as failed, and allows no more than one node to fail before marking the -entire updating run as failed. Because the command specifies the **Force** parameter, the cmdlet runs -without displaying confirmation prompts. +This command performs a scan and a full Updating Run on the cluster named **CONTOSO-FC1**. This +cmdlet uses the **Microsoft.WindowsUpdatePlugin** plug-in and requires that all cluster nodes be +online before the running this cmdlet. In addition, this cmdlet allows no more than three retries +per node before marking the node as failed, and allows no more than one node to fail before marking +the entire Updating Run as failed. Because the command specifies the **Force** parameter, the +cmdlet runs without displaying confirmation prompts. This example uses splatting to pass parameter values from the `$parameters` variable to the command. Learn more about [Splatting](/powershell/module/microsoft.powershell.core/about/about_splatting). -### Example 2: Preform a scan and a full updating run on the specified cluster using multiple plug-ins +### Example 2: Perform a scan and full Updating Run on the specified cluster using multiple plug-ins ```powershell $parameters = @{ @@ -97,11 +118,11 @@ $parameters = @{ Invoke-CauRun @parameters ``` -This command performs a scan and a full updating run on the cluster named CONTOSO-FC1. This cmdlet -uses the **Microsoft.WindowsUpdatePlugin** plug-in with the default configuration, and the +This command performs a scan and a full Updating Run on the cluster named **CONTOSO-FC1**. This +cmdlet uses the **Microsoft.WindowsUpdatePlugin** plug-in with the default configuration, and the **Microsoft.HotfixPlugin** plug-in using the hotfix root folder `\\CauHotfixSrv\shareName` and the default hotfix configuration file. If it isn't already enabled, the **Remote Shutdown** Windows -Firewall rule group is enabled on each cluster node before the updating run. If a failure occurs +Firewall rule group is enabled on each cluster node before the Updating Run. If a failure occurs during the installation of updates on a node by **Microsoft.WindowsUpdatePlugin**, updates aren't applied by **Microsoft.HotfixPlugin plug-in**. If the installation of updates by **Microsoft.WindowsUpdatePlugin** requires a node to restart, the node restarts before @@ -111,64 +132,91 @@ parameter, the cmdlet runs without displaying confirmation prompts. This example uses splatting to pass parameter values from the `$parameters` variable to the command. Learn more about [Splatting](/powershell/module/microsoft.powershell.core/about/about_splatting). -### Example 3: Recover from a previous updating run that failed on the specified cluster +### Example 3: Recover from a previous Updating Run that failed on the specified cluster ```powershell -Invoke-CauRun -ClusterName "CONTOSO-FC1"-ForceRecovery -Force +Invoke-CauRun -ClusterName "CONTOSO-FC1" -ForceRecovery -Force ``` -This command recovers from a previous updating run that failed and left the cluster in a Locked -state for the cluster named CONTOSO-FC1. Because the command specifies the **Force** parameter, the -recovery is performed without confirmation prompts. +This command recovers from a previous Updating Run that failed and left the cluster in a Locked +state for the cluster named **CONTOSO-FC1**. Because the command specifies the **Force** parameter, +the recovery is performed without confirmation prompts. ## PARAMETERS +### -AttemptSoftReboot + +Indicates that command attempts a Kernel Soft Reboot (KSR) for the failover cluster. + +KSR bypasses BIOS/firmware initialization. You can only use KSR for updates that do not require a +BIOS/firmware initialization. + +```yaml +Type: SwitchParameter +Parameter Sets: DefaultParamSet +Aliases: + +Required: False +Position: Named +Default value: None +Accept pipeline input: False +Accept wildcard characters: False +``` + ### -CauPluginArguments -Specifies a set of name=value pairs for each updating plug-in to use. +Specifies a set of name=value pairs, as arguments, for each updating plug-in to use. + For instance, to specify a Domain argument for one plug-in: + - `@{Domain=Domain.local}` -You can specify multiple pairs in a set separated with semicolons. -For instance: -- `@{name1=value1;name2=value2;name3=value3}` These name=value pairs must be meaningful to the - **CauPluginName** that you specify. If you specify arguments for more than one plug-in, provide - the sets of name=value pairs in the order that you pass values in **CauPluginName**, separated by - commas. For instance: + +You can specify multiple pairs in a set separated with semicolons. For instance: + +- `@{name1=value1;name2=value2;name3=value3}` + +These name=value pairs must be meaningful to the **CauPluginName** parameter that you specify. If +you specify arguments for more than one plug-in, provide the sets of name=value pairs in the order +that you pass values in **CauPluginName**, separated by commas. For instance: + - `@{name1=value1;name2=value2;name3=value3},@{name4=value4;name5=value5}` -For the default **Microsoft.WindowsUpdatePlugin** plug-in, no arguments are needed. -The following arguments are optional: -- **'IncludeRecommendedUpdates'='\'**: Boolean value to indicate that recommended updates will be applied in addition to important updates on each node. -If not specified, the default value is **'False'**. --- A standard Windows Update Agent query string that specifies criteria used by the Windows Update -Agent to filter the updates that will be applied to each node. For a name, use **QueryString** and -for a value, enclose the full query in quotation marks. If not specified, then the -**Microsoft.WindowsUpdatePlugin** plug-in by default uses the following argument: +For the default **Microsoft.WindowsUpdatePlugin** plug-in, no arguments are needed. The following +arguments are optional: + +- **'IncludeRecommendedUpdates'='\'**: Boolean value to indicate that recommended updates + will be applied in addition to important updates on each node. If not specified, the default value + is False. +- A standard Windows Update Agent query string that specifies criteria used by the Windows Update + Agent to filter the updates that will be applied to each node. For a name, use **QueryString** and + for a value, enclose the full query in quotation marks. If not specified, then the + **Microsoft.WindowsUpdatePlugin** plug-in by default uses the following argument: - `QueryString="IsInstalled=0 and Type='Software' and IsHidden=0 and IsAssigned=1"` For more information about query strings for the default **Microsoft.WindowsUpdatePlugin** plug-in and the criteria such as IsInstalled that can be included in the query strings, see -[IUpdateSearcher::Search method](https://go.microsoft.com/fwlink/p/?LinkId=223304). +[IUpdateSearcher::Search method](/windows/win32/api/wuapi/nf-wuapi-iupdatesearcher-search). For the **Microsoft.HotfixPlugin** plug-in, the following argument is required: -- **HotfixRootFolderPath**: The UNC path to a hotfix root folder in an SMB share with a structure - that contains the updates to apply and that contains the hotfix configuration file. + +- **HotfixRootFolderPath=\**: The UNC path to a hotfix root folder in an SMB share with a + structure that contains the updates to apply and that contains the hotfix configuration file. The following arguments are optional for the **Microsoft.HotfixPlugin** plug-in: -- **RequireSmbEncryption=\**: Boolean value to indicate that SMB Encryption is enforced for - data accessed from the SMB share. If not specified, the default value is False. To ensure the + +- **RequireSmbEncryption=\**: Boolean value to indicate that SMB Encryption will be enforced + for accessing data from the SMB share. If not specified, the default value is False. To ensure the integrity of the data accessed from the SMB share, the plug-in requires that the share is enabled for either SMB signing or SMB Encryption. -- **DisableAclChecks=\**: Boolean value to indicate that the plug-in checks for sufficient - permissions on the hotfix root folder and the hotfix configuration file. If not specified, the - default value is False. +- **DisableAclChecks=\**: Boolean value to indicate that the plug-in will check for + sufficient permissions on the hotfix root folder and the hotfix configuration file. If not + specified, the default value is False. - **HotfixInstallerTimeoutMinutes=\**: The length of time in minutes that the plug-in allows the hotfix installer process to return. If not specified, the default value is 30 minutes. -- **HotfixConfigFileName=\**: Name for the hotfix configuration file. -If not specified, the default name DefaultHotfixConfig.xml is used. - -For more information about required and optional arguments for the **Microsoft.HotfixPlugin** -plug-in, see [How CAU Plug-ins Work](https://go.microsoft.com/fwlink/p/?LinkId=235333). +- **HotfixConfigFileName=\**: Name for the hotfix configuration file. If not specified, the + default name `DefaultHotfixConfig.xml` is used. For more information about required and optional + arguments for the **Microsoft.HotfixPlugin** plug-in, see + [How Cluster-Aware Updating plug-ins work](/windows-server/failover-clustering/cluster-aware-updating-plug-ins). ```yaml Type: Hashtable[] @@ -189,7 +237,7 @@ separated with commas. The default is the **Microsoft.WindowsUpdatePlugin** plug coordinates the Windows Update Agent software resident on each cluster node, the same software that is used when updates are downloaded from Windows Update or Microsoft Update, or from a Windows Server Update Services (WSUS) server. For more information about how plug-ins work with CAU, see -[How CAU Plug-ins Work](https://go.microsoft.com/fwlink/p/?LinkId=235333). +[How Cluster-Aware Updating plug-ins work](/windows-server/failover-clustering/cluster-aware-updating-plug-ins). ```yaml Type: String[] @@ -197,7 +245,24 @@ Parameter Sets: DefaultParamSet Aliases: Required: False -Position: 1 +Position: Named +Default value: None +Accept pipeline input: False +Accept wildcard characters: False +``` + +### -ClearCorruptReports + +Specifies whether to clear any corrupt reports that were generated during a previous run of the +Cluster-Aware Updating (CAU) tool to recover from a failed or interrupted update run. + +```yaml +Type: SwitchParameter +Parameter Sets: RecoverParamSet +Aliases: + +Required: False +Position: Named Default value: None Accept pipeline input: False Accept wildcard characters: False @@ -239,22 +304,6 @@ Accept pipeline input: False Accept wildcard characters: False ``` -### -Confirm - -Prompts you for confirmation before running the cmdlet. - -```yaml -Type: SwitchParameter -Parameter Sets: (All) -Aliases: cf - -Required: False -Position: Named -Default value: False -Accept pipeline input: False -Accept wildcard characters: False -``` - ### -Credential Specifies the administrative credentials for the target cluster. @@ -265,7 +314,7 @@ Parameter Sets: (All) Aliases: Required: False -Position: 2 +Position: Named Default value: None Accept pipeline input: False Accept wildcard characters: False @@ -275,13 +324,14 @@ Accept wildcard characters: False Enables the **Remote Shutdown** Windows Firewall rule group on each cluster node, if it isn't already enabled. If the **EnableFirewallRules** parameter is specified, CAU automatically re-enables -the **Remote Shutdown** rule group each time the CAU clustered role performs an updating run, in -case the rules are disabled manually in the intervening time. Enabling this rule group permits -inbound communication to each cluster node during each updating run that allows CAU to shut down and -restart the node remotely (if the installation of an update requires a restart). If Windows Firewall -is in use on the cluster nodes and the rule group isn't enabled, the updating run will fail. The -**Remote Shutdown** Windows Firewall rule group isn't enabled when it will conflict with Group -Policy settings that are configured for Windows Firewall. +the **Remote Shutdown** rule group each time the CAU clustered role performs an Updating Run, in +case the rules are disabled manually in the intervening time. + +Enabling this rule group permits inbound communication to each cluster node during each updating +run that allows CAU to shut down and restart the node remotely (if the installation of an update +requires a restart). If Windows Firewall is in use on the cluster nodes and the rule group isn't +enabled, the Updating Run will fail. The **Remote Shutdown** Windows Firewall rule group isn't +enabled when it will conflict with Group Policy settings that are configured for Windows Firewall. ```yaml Type: SwitchParameter @@ -301,11 +351,11 @@ Specifies the method used to bring drained workloads back to the node, at the en node. Drained workloads are workloads that were previously run on the node, but were moved to another node. The acceptable values for this parameter are: -- NoFailback -- Immediate -- Policy +- `NoFailback` +- `Immediate` +- `Policy` -The default value is Immediate. +The default value is `Immediate`. ```yaml Type: FailbackType @@ -336,6 +386,60 @@ Accept pipeline input: False Accept wildcard characters: False ``` +### -ForcePauseAndDrain + +Indicates that the command forces cluster nodes to pause and drain roles. + +A forced drain moves the roles off of the draining node even if the group cannot move. A group +might not be able to move because no other node can host the group or the group is locked. + +```yaml +Type: SwitchParameter +Parameter Sets: (All) +Aliases: + +Required: False +Position: Named +Default value: None +Accept pipeline input: False +Accept wildcard characters: False +``` + +### -ForcePauseDrainAndReboot + +Indicates that the command forces cluster nodes to pause, drain roles, and restart. + +A forced drain moves the roles off of the draining node even if the group cannot move. A group +might not be able to move because no other node can host the group or the group is locked. + +```yaml +Type: SwitchParameter +Parameter Sets: (All) +Aliases: + +Required: False +Position: Named +Default value: None +Accept pipeline input: False +Accept wildcard characters: False +``` + +### -ForcePauseNoDrain + +Indicates that the command forces cluster nodes to pause. The nodes are not drained. + +```yaml +Type: SwitchParameter +Parameter Sets: (All) +Aliases: + +Required: False +Position: Named +Default value: None +Accept pipeline input: False +Accept wildcard characters: False +``` + ### -ForceRecovery Indicates that the cmdlet recovers from a previous failed run that left the cluster in a Locked @@ -356,12 +460,28 @@ Accept pipeline input: False Accept wildcard characters: False ``` +### -ForceSelfUpdate + +Specifies whether to update the CAU plugin on the local computer before running the update. + +```yaml +Type: SwitchParameter +Parameter Sets: (All) +Aliases: + +Required: False +Position: Named +Default value: None +Accept pipeline input: False +Accept wildcard characters: False +``` + ### -MaxFailedNodes -Specifies the maximum number of nodes on which updating can fail. -If one more than this number of nodes fails, then the updating run is stopped. -The range is from zero (0) through 1 less than the number of cluster nodes. -The default for most clusters is approximately one-third of the number of nodes. +Specifies the maximum number of nodes on which updating can fail. If one more than this number of +nodes fails, then the Updating Run is stopped. The range is from zero (0) through 1 less than the +number of cluster nodes. The default for most clusters is approximately one-third of the number of +nodes. ```yaml Type: Int32 @@ -378,7 +498,7 @@ Accept wildcard characters: False ### -MaxRetriesPerNode Specifies the maximum number of times that the update process (including any pre-update and -post-update scripts) is retried per node. The maximum is 64 and the default is 3. +post-update scripts) is retried per node. The maximum is **64** and the default is **3**. ```yaml Type: Int32 @@ -408,11 +528,28 @@ Accept pipeline input: False Accept wildcard characters: False ``` +### -OsRollingUpgrade + +Indicates that the CAU cluster role upgrades the operating system of the cluster nodes without +stopping the Hyper-V or the Scale-Out File Server workloads. + +```yaml +Type: SwitchParameter +Parameter Sets: DefaultParamSet +Aliases: + +Required: False +Position: Named +Default value: None +Accept pipeline input: False +Accept wildcard characters: False +``` + ### -PostUpdateScript Specifies the path and file name for a Windows PowerShell script to run on each node after updating finishes, and just after the node is brought out of Maintenance mode. The file name extension must -be .ps1 and the total length of the path plus the file name must be no longer than 260 characters. +be `.ps1` and the total length of the path plus the file name must be no longer than 260 characters. As a best practice, the script should be located on a disk in cluster storage, or at a highly available network share, to ensure that it is always accessible to all the cluster nodes. @@ -431,7 +568,7 @@ Accept wildcard characters: False ### -PreUpdateScript Specifies the path and file name for a Windows PowerShell script to run on each node before updating -begins, and before the node is put into Maintenance mode. The file name extension must be .ps1 and +begins, and before the node is put into Maintenance mode. The file name extension must be `.ps1` and the total length of the path plus the file name must be no longer than 260 characters. As a best practice, the script should be located on a disk in cluster storage, or at a highly available network share, to ensure that the script is always accessible to all the cluster nodes. If a @@ -449,10 +586,34 @@ Accept pipeline input: False Accept wildcard characters: False ``` +### -RebootMode + +Specifies the type of reboot to use for each node in the cluster during the update. The available +values are: + +- `ClusProp` +- `FullReboot` +- `SoftReboot` +- `PluginCustomReboot` +- `OrchestratorDefault` + +```yaml +Type: RebootType +Parameter Sets: DefaultParamSet +Aliases: +Accepted values: ClusProp, FullReboot, SoftReboot, PluginCustomReboot, OrchestratorDefault + +Required: False +Position: Named +Default value: None +Accept pipeline input: False +Accept wildcard characters: False +``` + ### -RebootTimeoutMinutes Specifies the time in minutes that CAU allows for the restarting of a node. If the restart doesn't -complete within this time, then the updating run on that node is marked as failed. +complete within this time, then the Updating Run on that node is marked as failed. ```yaml Type: Int32 @@ -482,16 +643,32 @@ Accept pipeline input: False Accept wildcard characters: False ``` +### -ResumeNode + +Specifies the name of a node in the cluster to resume updating if it was previously suspended. + +```yaml +Type: String +Parameter Sets: ResumeNodeParamSet +Aliases: + +Required: True +Position: Named +Default value: None +Accept pipeline input: False +Accept wildcard characters: False +``` + ### -RunPluginsSerially Indicates that CAU will scan each cluster node for applicable updates and stage the updates for each plug-in in the plug-in order passed into the **CauPluginName** parameter when multiple plug-ins are -used during an updating run. By default, CAU scans and stages the applicable updates for all +used during an Updating Run. By default, CAU scans and stages the applicable updates for all plug-ins in parallel. Regardless of the configuration of this parameter, CAU installs the applicable updates for each plug-in sequentially. -The parameter is valid only when multiple plug-ins are specified for the **CauPluginName** parameter. -If a single plug-in is specified, a warning appears. +The parameter is valid only when multiple plug-ins are specified for the **CauPluginName** +parameter. If a single plug-in is specified, a warning appears. ```yaml Type: SwitchParameter @@ -509,11 +686,11 @@ Accept wildcard characters: False Indicates that CAU will shut down and restart a cluster node after each plug-in installs updates on the node, if the installation of an update by a plug-in requires a restart when multiple plug-ins -are used during an updating run. By default, during an updating run, all plug-ins complete the +are used during an Updating Run. By default, during an Updating Run, all plug-ins complete the installation of updates on a cluster node before the node restarts one time. -The parameter is valid only when multiple plug-ins are specified for the **CauPluginName** parameter. -If a single plug-in is specified, a warning appears. +The parameter is valid only when multiple plug-ins are specified for the **CauPluginName** +parameter. If a single plug-in is specified, a warning appears. ```yaml Type: SwitchParameter @@ -527,11 +704,45 @@ Accept pipeline input: False Accept wildcard characters: False ``` +### -SiteAwareUpdatingOrder + +Specifies the order in which the command updates cluster nodes. + +By default, CAU selects the order of nodes to update based on the level of activity. + +```yaml +Type: String[] +Parameter Sets: DefaultParamSet +Aliases: + +Required: False +Position: Named +Default value: None +Accept pipeline input: False +Accept wildcard characters: False +``` + +### -SkipUpdateChecks + +Indicates that the command skips update checks. + +```yaml +Type: SwitchParameter +Parameter Sets: (All) +Aliases: + +Required: False +Position: Named +Default value: None +Accept pipeline input: False +Accept wildcard characters: False +``` + ### -StopAfter -Specifies the time in minutes after which the updating run is canceled if it hasn't completed. The +Specifies the time in minutes after which the Updating Run is canceled if it hasn't completed. The time span can be expressed in the standard ways available in Windows PowerShell, for instance, -01:30:00 represents one hour and thirty minutes. By default, the updating run is allowed an +01:30:00 represents one hour and thirty minutes. By default, the Updating Run is allowed an unlimited amount of time to complete. If pre-update or post-update scripts are specified, then the entire process of running scripts and @@ -553,11 +764,11 @@ Accept wildcard characters: False Indicates that if a failure occurs during the application of updates on a node by any plug-in, subsequent updates on the node that are coordinated by the remaining plug-ins are stopped when -multiple plug-ins are used during an updating run. By default, a failure by one plug-in doesn't +multiple plug-ins are used during an Updating Run. By default, a failure by one plug-in doesn't affect the application of updates on a node by other plug-ins. -The parameter is valid only when multiple plug-ins are specified for the **CauPluginName** parameter. -If a single plug-in is specified, a warning appears. +The parameter is valid only when multiple plug-ins are specified for the **CauPluginName** +parameter. If a single plug-in is specified, a warning appears. ```yaml Type: SwitchParameter @@ -596,11 +807,60 @@ Accept pipeline input: False Accept wildcard characters: False ``` +### -SuspendNode + +Specifies the name of a node in the cluster to suspend updating. + +```yaml +Type: String +Parameter Sets: SuspendNodeParamSet +Aliases: + +Required: True +Position: Named +Default value: None +Accept pipeline input: False +Accept wildcard characters: False +``` + +### -SuspendRetriesPerNode + +Specifies the number of times to retry suspending a node before moving on to the next node. + +```yaml +Type: Int32 +Parameter Sets: DefaultParamSet +Aliases: + +Required: False +Position: Named +Default value: None +Accept pipeline input: False +Accept wildcard characters: False +``` + +### -WaitForStorageRepairTimeoutMinutes + +Specifies the amount of time in minutes to wait for storage to be repaired on a node before +continuing with an update. + +```yaml +Type: Int32 +Parameter Sets: DefaultParamSet +Aliases: + +Required: False +Position: Named +Default value: None +Accept pipeline input: False +Accept wildcard characters: False +``` + ### -WarnAfter -Specifies the time in minutes after which a warning is logged if the updating run, including any +Specifies the time in minutes after which a warning is logged if the Updating Run, including any pre-update and post-update scripts, hasn't completed. By default, no warning is logged, regardless -of the time taken by the updating run. +of the time taken by the Updating Run. ```yaml Type: TimeSpan @@ -614,10 +874,25 @@ Accept pipeline input: False Accept wildcard characters: False ``` +### -Confirm + +Prompts you for confirmation before running the cmdlet. + +```yaml +Type: SwitchParameter +Parameter Sets: (All) +Aliases: cf + +Required: False +Position: Named +Default value: None +Accept pipeline input: False +Accept wildcard characters: False +``` + ### -WhatIf -Shows what would happen if the cmdlet runs. -The cmdlet isn't run. +Shows what would happen if the cmdlet runs. The cmdlet is not run. ```yaml Type: SwitchParameter @@ -626,7 +901,7 @@ Aliases: wi Required: False Position: Named -Default value: False +Default value: None Accept pipeline input: False Accept wildcard characters: False ``` @@ -636,7 +911,7 @@ Accept wildcard characters: False This cmdlet supports the common parameters: -Debug, -ErrorAction, -ErrorVariable, -InformationAction, -InformationVariable, -OutVariable, -OutBuffer, -PipelineVariable, -Verbose, -WarningAction, and -WarningVariable. For more information, see -[about_CommonParameters](https://go.microsoft.com/fwlink/?LinkID=113216). +[about_CommonParameters](/powershell/module/microsoft.powershell.core/about/about_commonparameters). ## INPUTS @@ -654,17 +929,16 @@ This cmdlet supports the common parameters: -Debug, -ErrorAction, -ErrorVariable ### Microsoft.ClusterAwareUpdating.UpdateInfo -### Microsoft.ClusterAwareUpdating.UpdateInstallResult - ### Microsoft.ClusterAwareUpdating.UpdateStagingResult ## NOTES ## RELATED LINKS -[Add-CauClusterRole](./Add-CauClusterRole.md) +[Add-CauClusterRole](add-cauclusterrole.md) -[Get-CauRun](./Get-CauRun.md) +[Get-CauRun](get-caurun.md) -[Stop-CauRun](./Stop-CauRun.md) +[Invoke-CauScan](invoke-causcan.md) +[Stop-CauRun](stop-caurun.md) diff --git a/docset/winserver2025-ps/clusterawareupdating/Invoke-CauScan.md b/docset/winserver2025-ps/clusterawareupdating/Invoke-CauScan.md index 2e2af36bd6..36b3bd5c89 100644 --- a/docset/winserver2025-ps/clusterawareupdating/Invoke-CauScan.md +++ b/docset/winserver2025-ps/clusterawareupdating/Invoke-CauScan.md @@ -2,7 +2,7 @@ description: Use this topic to help manage Windows and Windows Server technologies with Windows PowerShell. external help file: ClusterAwareUpdating.dll-Help.xml Module Name: ClusterAwareUpdating -ms.date: 09/27/2022 +ms.date: 07/01/2024 online version: https://learn.microsoft.com/powershell/module/clusterawareupdating/invoke-causcan?view=windowsserver2025-ps&wt.mc_id=ps-gethelp schema: 2.0.0 title: Invoke-CauScan @@ -11,15 +11,14 @@ title: Invoke-CauScan # Invoke-CauScan ## SYNOPSIS -Performs a scan of cluster nodes for applicable updates and gets a list of the initial set of -updates that are applied to each node in a specified cluster. +Performs a scan of cluster nodes for applicable updates and gets a list of the initial set of updates that are applied to each node in a specified cluster. ## SYNTAX ``` -Invoke-CauScan [[-ClusterName] ] [[-CauPluginName] ] [[-Credential] -] [-CauPluginArguments ] [-RunPluginsSerially] [-StopOnPluginFailure] - [] +Invoke-CauScan [[-ClusterName] ] [-AttemptSoftReboot] [-CauPluginName ] + [-Credential ] [-CauPluginArguments ] [-RunPluginsSerially] + [-StopOnPluginFailure] [-OsRollingUpgrade] [-RebootMode ] [] ``` ## DESCRIPTION @@ -43,10 +42,10 @@ Invoke-CauScan -ClusterName "CONTOSO-FC1" -CauPluginName "Microsoft.WindowsUpdat ``` This command gets a detailed list of the initial set of updates that would currently be applied to -each node in the cluster named CONTOSO-FC1. The list is based on the updates that would be applied -by the **Microsoft.WindowsUpdatePlugin** plug-in, which is the default plug-in. The preview list -includes only an initial set of updates, and doesn't include updates that might become applicable -only after the initial updates are installed. +each node in the cluster named **CONTOSO-FC1**. The list is based on the updates that would be +applied by the **Microsoft.WindowsUpdatePlugin** plug-in, which is the default plug-in. The preview +list includes only an initial set of updates, and doesn't include updates that might become +applicable only after the initial updates are installed. ### Example 2: Get a detailed list of the initial set of updates on the specified cluster using a query string @@ -67,32 +66,57 @@ Invoke-CauScan $parameters -Credential $Cred ``` This example gets a detailed list of the initial set of updates that would currently be applied to -each node in the cluster named CONTOSO-FC1. The list is based on the updates that would be applied +each node in the cluster named **CONTOSO-FC1**. The list is based on the updates that would be applied by the **Microsoft.WindowsUpdatePlugin** plug-in, using a specified query string, and the **Microsoft.HotfixPlugin**, after the necessary hotfixes and the hotfix configuration file have been downloaded to `\\CauHotfixSrv\shareName`. This example also shows how to pass the administrative -credentials for cluster CONTOSO-FC1 to the cmdlet. +credentials for cluster **CONTOSO-FC1** to the cmdlet. This example uses splatting to pass parameter values from the `$parameters` variable to the command. Learn more about [Splatting](/powershell/module/microsoft.powershell.core/about/about_splatting). ## PARAMETERS +### -AttemptSoftReboot + +Indicates that command assumes a Kernel Soft Reboot (KSR) for the failover cluster. + +KSR bypasses BIOS/firmware initialization. You can only use KSR for updates that do not require a +BIOS/firmware initialization. + +```yaml +Type: SwitchParameter +Parameter Sets: (All) +Aliases: + +Required: False +Position: Named +Default value: None +Accept pipeline input: False +Accept wildcard characters: False +``` + ### -CauPluginArguments -Specifies a set of name=value pairs for each updating plug-in to use. -For instance, to specify a **Domain** argument for one plug-in: +Specifies a set of name=value pairs, as arguments, for each updating plug-in to use. + +For instance, to specify a Domain argument for one plug-in: + - `@{Domain=Domain.local}` -You can specify multiple pairs in a set separated with semicolons. -For instance: -- `@{name1=value1;name2=value2;name3=value3}` These name=value pairs must be meaningful to the - **CauPluginName** parameter that you specify. If you specify arguments for more than one plug-in, - provide the sets of name=value pairs in the order that you pass values into the **CauPluginName** - parameter, separated by commas. For instance: + +You can specify multiple pairs in a set separated with semicolons. For instance: + +- `@{name1=value1;name2=value2;name3=value3}` + +These name=value pairs must be meaningful to the **CauPluginName** parameter that you specify. If +you specify arguments for more than one plug-in, provide the sets of name=value pairs in the order +that you pass values in **CauPluginName**, separated by commas. For instance: + - `@{name1=value1;name2=value2;name3=value3},@{name4=value4;name5=value5}` -For the default **Microsoft.WindowsUpdatePlugin** plug-in, no arguments are needed. -The following arguments are optional: +For the default **Microsoft.WindowsUpdatePlugin** plug-in, no arguments are needed. The following +arguments are optional: + - **'IncludeRecommendedUpdates'='\'**: Boolean value to indicate that recommended updates will be applied in addition to important updates on each node. If not specified, the default value is False. @@ -104,14 +128,15 @@ The following arguments are optional: For more information about query strings for the default **Microsoft.WindowsUpdatePlugin** plug-in and the criteria such as IsInstalled that can be included in the query strings, see -[IUpdateSearcher::Search method](https://go.microsoft.com/fwlink/p/?LinkId=223304). +[IUpdateSearcher::Search method](/windows/win32/api/wuapi/nf-wuapi-iupdatesearcher-search). + +For the **Microsoft.HotfixPlugin** plug-in, the following argument is required: -For the **Microsoft.HotfixPlugin** plug-in. -the following argument is required: - **HotfixRootFolderPath=\**: The UNC path to a hotfix root folder in an SMB share with a - structure that contains the updates to apply and that contains the hotfix configuration file + structure that contains the updates to apply and that contains the hotfix configuration file. The following arguments are optional for the **Microsoft.HotfixPlugin** plug-in: + - **RequireSmbEncryption=\**: Boolean value to indicate that SMB Encryption will be enforced for accessing data from the SMB share. If not specified, the default value is False. To ensure the integrity of the data accessed from the SMB share, the plug-in requires that the share is enabled @@ -122,10 +147,9 @@ The following arguments are optional for the **Microsoft.HotfixPlugin** plug-in: - **HotfixInstallerTimeoutMinutes=\**: The length of time in minutes that the plug-in allows the hotfix installer process to return. If not specified, the default value is 30 minutes. - **HotfixConfigFileName=\**: Name for the hotfix configuration file. If not specified, the - default name DefaultHotfixConfig.xml is used. - -For more information about required and optional arguments for the **Microsoft.HotfixPlugin** -plug-in, see [How CAU Plug-ins Work](https://go.microsoft.com/fwlink/p/?LinkId=235333). + default name `DefaultHotfixConfig.xml` is used. For more information about required and optional + arguments for the **Microsoft.HotfixPlugin** plug-in, see + [How Cluster-Aware Updating plug-ins work](/windows-server/failover-clustering/cluster-aware-updating-plug-ins). ```yaml Type: Hashtable[] @@ -147,7 +171,7 @@ coordinates the Windows Update Agent software resident on each cluster node, the is used when updates are downloaded from Windows Update or Microsoft Update, or from a Windows Server Update Services (WSUS) server. For more information about how plug-ins work with Cluster-Aware Updating (CAU), see -[Cluster-Aware Updating plug-ins](https://go.microsoft.com/fwlink/p/?LinkId=235333). +[How Cluster-Aware Updating plug-ins work](/windows-server/failover-clustering/cluster-aware-updating-plug-ins). ```yaml Type: String[] @@ -155,7 +179,7 @@ Parameter Sets: (All) Aliases: Required: False -Position: 1 +Position: Named Default value: None Accept pipeline input: False Accept wildcard characters: False @@ -189,7 +213,48 @@ Parameter Sets: (All) Aliases: Required: False -Position: 2 +Position: Named +Default value: None +Accept pipeline input: False +Accept wildcard characters: False +``` + +### -OsRollingUpgrade + +Indicates that the CAU cluster role scans for upgrades to the operating system of the cluster nodes +without stopping the Hyper-V or the Scale-Out File Server workloads. + +```yaml +Type: SwitchParameter +Parameter Sets: (All) +Aliases: + +Required: False +Position: Named +Default value: None +Accept pipeline input: False +Accept wildcard characters: False +``` + +### -RebootMode + +Specifies the type of reboot to use for each node in the cluster during the update. The available +values are: + +- `ClusProp` +- `FullReboot` +- `SoftReboot` +- `PluginCustomReboot` +- `OrchestratorDefault` + +```yaml +Type: RebootType +Parameter Sets: (All) +Aliases: +Accepted values: ClusProp, FullReboot, SoftReboot, PluginCustomReboot, OrchestratorDefault + +Required: False +Position: Named Default value: None Accept pipeline input: False Accept wildcard characters: False @@ -199,11 +264,11 @@ Accept wildcard characters: False Indicates that CAU scans each cluster node for applicable updates and stages the updates for each plug-in in the plug-in order passed into the **CauPluginName** parameter then multiple plug-ins are -used during a scan for updates +used during a scan for updates. -By default, CAU scans and stages the applicable updates for all plug-ins in parallel. -This parameter is valid only when multiple plug-ins are specified in the **CauPluginName** parameter. -If a single plug-in is specified, a warning appears. +By default, CAU scans and stages the applicable updates for all plug-ins in parallel. This +parameter is valid only when multiple plug-ins are specified in the **CauPluginName** parameter. If +a single plug-in is specified, a warning appears. ```yaml Type: SwitchParameter @@ -243,7 +308,7 @@ Accept wildcard characters: False This cmdlet supports the common parameters: -Debug, -ErrorAction, -ErrorVariable, -InformationAction, -InformationVariable, -OutVariable, -OutBuffer, -PipelineVariable, -Verbose, -WarningAction, and -WarningVariable. For more information, see -[about_CommonParameters](https://go.microsoft.com/fwlink/?LinkID=113216). +[about_CommonParameters](/powershell/module/microsoft.powershell.core/about/about_commonparameters). ## INPUTS @@ -251,11 +316,20 @@ This cmdlet supports the common parameters: -Debug, -ErrorAction, -ErrorVariable ## OUTPUTS -### Microsoft.ClusterAwareUpdating.CauUpdateInfo +### Microsoft.ClusterAwareUpdating.ActivityIdMap + +### Microsoft.ClusterAwareUpdating.UpdateInfo + +### Microsoft.ClusterAwareUpdating.UpgradeSetupInfo ## NOTES ## RELATED LINKS -[Invoke-CauRun](./Invoke-CauRun.md) +[Add-CauClusterRole](add-cauclusterrole.md) + +[Get-CauRun](get-caurun.md) + +[Invoke-CauRun](invoke-caurun.md) +[Stop-CauRun](stop-caurun.md) diff --git a/docset/winserver2025-ps/clusterawareupdating/Invoke-ClusterlessCauRun.md b/docset/winserver2025-ps/clusterawareupdating/Invoke-ClusterlessCauRun.md new file mode 100644 index 0000000000..709dc6a4d7 --- /dev/null +++ b/docset/winserver2025-ps/clusterawareupdating/Invoke-ClusterlessCauRun.md @@ -0,0 +1,462 @@ +--- +description: Use this topic to help manage Windows and Windows Server technologies with Windows PowerShell. +external help file: ClusterAwareUpdating.dll-Help.xml +Module Name: ClusterAwareUpdating +ms.date: 07/01/2024 +online version: https://learn.microsoft.com/powershell/module/clusterawareupdating/invoke-clusterlesscaurun?view=windowsserver2025-ps&wt.mc_id=ps-gethelp +schema: 2.0.0 +title: Invoke-ClusterlessCauRun +--- + +# Invoke-ClusterlessCauRun + +## SYNOPSIS +Performs a Cluster-Aware Updating (CAU) run on a set of nodes that are not associated with a cluster. + +## SYNTAX + +### DefaultParamSet (Default) + +``` +Invoke-ClusterlessCauRun [-MaxRetries ] [-RebootTimeoutMinutes ] + [-EnableFirewallRules] [-PreUpdateScript ] [-PostUpdateScript ] + [-ConfigurationName ] [-Force] [-CauPluginName ] [-Credential ] + [-CauPluginArguments ] [-RunPluginsSerially] [-StopOnPluginFailure] + [-OsRollingUpgrade] [-RebootMode ] [-WhatIf] [-Confirm] [] +``` + +### RecoverParamSet + +``` +Invoke-ClusterlessCauRun [-ForceRecovery] [-Force] [-Credential ] [-WhatIf] [-Confirm] + [] +``` + +## DESCRIPTION + +The `Invoke-ClusterlessCauRun` cmdlet performs a CAU run on a set of nodes that are not associated +with a cluster. This cmdlet can be used to update standalone servers or groups of servers that are +not part of a cluster. + +## EXAMPLES + +### Example 1 + +```powershell +Invoke-ClusterlessCauRun -MaxRetries 3 +``` + +This example performs a CAU run on the specified nodes, with a maximum of 3 retries for each node +that fails to update. + +## PARAMETERS + +### -CauPluginArguments + +Specifies a set of name=value pairs, as arguments, for each updating plug-in to use. + +For instance, to specify a Domain argument for one plug-in: + +- `@{Domain=Domain.local}` + +You can specify multiple pairs in a set separated with semicolons. For instance: + +- `@{name1=value1;name2=value2;name3=value3}` + +These name=value pairs must be meaningful to the **CauPluginName** parameter that you specify. If +you specify arguments for more than one plug-in, provide the sets of name=value pairs in the order +that you pass values in **CauPluginName**, separated by commas. For instance: + +- `@{name1=value1;name2=value2;name3=value3},@{name4=value4;name5=value5}` + +For the default **Microsoft.WindowsUpdatePlugin** plug-in, no arguments are needed. The following +arguments are optional: + +- **'IncludeRecommendedUpdates'='\'**: Boolean value to indicate that recommended updates + will be applied in addition to important updates on each node. If not specified, the default value + is False. +- A standard Windows Update Agent query string that specifies criteria used by the Windows Update + Agent to filter the updates that will be applied to each node. For a name, use **QueryString** and + for a value, enclose the full query in quotation marks. If not specified, then the + **Microsoft.WindowsUpdatePlugin** plug-in by default uses the following argument: +- `QueryString="IsInstalled=0 and Type='Software' and IsHidden=0 and IsAssigned=1"` + +For more information about query strings for the default **Microsoft.WindowsUpdatePlugin** plug-in +and the criteria such as IsInstalled that can be included in the query strings, see +[IUpdateSearcher::Search method](/windows/win32/api/wuapi/nf-wuapi-iupdatesearcher-search). + +For the **Microsoft.HotfixPlugin** plug-in, the following argument is required: + +- **HotfixRootFolderPath=\**: The UNC path to a hotfix root folder in an SMB share with a + structure that contains the updates to apply and that contains the hotfix configuration file. + +The following arguments are optional for the **Microsoft.HotfixPlugin** plug-in: + +- **RequireSmbEncryption=\**: Boolean value to indicate that SMB Encryption will be enforced + for accessing data from the SMB share. If not specified, the default value is False. To ensure the + integrity of the data accessed from the SMB share, the plug-in requires that the share is enabled + for either SMB signing or SMB Encryption. +- **DisableAclChecks=\**: Boolean value to indicate that the plug-in will check for + sufficient permissions on the hotfix root folder and the hotfix configuration file. If not + specified, the default value is False. +- **HotfixInstallerTimeoutMinutes=\**: The length of time in minutes that the plug-in + allows the hotfix installer process to return. If not specified, the default value is 30 minutes. +- **HotfixConfigFileName=\**: Name for the hotfix configuration file. If not specified, the + default name `DefaultHotfixConfig.xml` is used. For more information about required and optional + arguments for the **Microsoft.HotfixPlugin** plug-in, see + [How Cluster-Aware Updating plug-ins work](/windows-server/failover-clustering/cluster-aware-updating-plug-ins). + +```yaml +Type: Hashtable[] +Parameter Sets: DefaultParamSet +Aliases: + +Required: False +Position: Named +Default value: None +Accept pipeline input: False +Accept wildcard characters: False +``` + +### -CauPluginName + +Specifies one or more plug-ins to use when performing scans. You can specify multiple values +separated with commas. The default is the **Microsoft.WindowsUpdatePlugin** plug-in. This plug-in +coordinates the Windows Update Agent software resident on each cluster node, the same software that +is used when updates are downloaded from Windows Update or Microsoft Update, or from a Windows +Server Update Services (WSUS) server. For more information about how plug-ins work with +Cluster-Aware Updating (CAU), see +[How Cluster-Aware Updating plug-ins work](/windows-server/failover-clustering/cluster-aware-updating-plug-ins). + +```yaml +Type: String[] +Parameter Sets: DefaultParamSet +Aliases: + +Required: False +Position: Named +Default value: None +Accept pipeline input: False +Accept wildcard characters: False +``` + +### -ConfigurationName + +Specifies the Windows PowerShell session configuration that defines the session in which scripts, +specified by the **PreUpdateScript** and **PostUpdateScript** parameters, and cmdlets are run, and +can limit the cmdlets that are available to be run. If either a pre-update or post-update script is +specified but a configuration name isn't specified, then the default session configuration that is +built into Windows PowerShell is used. + +```yaml +Type: String +Parameter Sets: DefaultParamSet +Aliases: + +Required: False +Position: Named +Default value: None +Accept pipeline input: False +Accept wildcard characters: False +``` + +### -Credential + +Specifies the administrative credentials for the target cluster. + +```yaml +Type: PSCredential +Parameter Sets: (All) +Aliases: + +Required: False +Position: Named +Default value: None +Accept pipeline input: False +Accept wildcard characters: False +``` + +### -EnableFirewallRules + +Enables the **Remote Shutdown** Windows Firewall rule group on each cluster node, if it isn't +already enabled. If the **EnableFirewallRules** parameter is specified, CAU automatically re-enables +the **Remote Shutdown** rule group each time the CAU clustered role performs an Updating Run, in +case the rules are disabled manually in the intervening time. + +Enabling this rule group permits inbound communication to each cluster node during each updating +run that allows CAU to shut down and restart the node remotely (if the installation of an update +requires a restart). If Windows Firewall is in use on the cluster nodes and the rule group isn't +enabled, the Updating Run will fail. The **Remote Shutdown** Windows Firewall rule group isn't +enabled when it will conflict with Group Policy settings that are configured for Windows Firewall. + +```yaml +Type: SwitchParameter +Parameter Sets: DefaultParamSet +Aliases: + +Required: False +Position: Named +Default value: None +Accept pipeline input: False +Accept wildcard characters: False +``` + +### -Force + +Forces the command to run without asking for user confirmation. + +```yaml +Type: SwitchParameter +Parameter Sets: (All) +Aliases: f + +Required: False +Position: Named +Default value: None +Accept pipeline input: False +Accept wildcard characters: False +``` + +### -ForceRecovery + +Indicates that the cmdlet recovers from a previous failed run that left the cluster in a Locked +state. + +This switch defeats the synchronization mechanism used to prevent two update coordinators from +accidentally updating the same cluster at the same time. Use with care. + +```yaml +Type: SwitchParameter +Parameter Sets: RecoverParamSet +Aliases: Recover + +Required: True +Position: Named +Default value: None +Accept pipeline input: False +Accept wildcard characters: False +``` + +### -MaxRetries + +Specifies the maximum number of times that a node should be retried if an update fails. This can be +useful if you want to ensure that all nodes are updated. + +```yaml +Type: Int32 +Parameter Sets: DefaultParamSet +Aliases: + +Required: False +Position: Named +Default value: None +Accept pipeline input: False +Accept wildcard characters: False +``` + +### -OsRollingUpgrade + +Indicates that the CAU cluster role upgrades the operating system of the cluster nodes without +stopping the Hyper-V or the Scale-Out File Server workloads. + +```yaml +Type: SwitchParameter +Parameter Sets: DefaultParamSet +Aliases: + +Required: False +Position: Named +Default value: None +Accept pipeline input: False +Accept wildcard characters: False +``` + +### -PostUpdateScript + +Specifies the path and file name for a Windows PowerShell script to run on each node after updating +finishes, and just after the node is brought out of Maintenance mode. The file name extension must +be `.ps1` and the total length of the path plus the file name must be no longer than 260 characters. +As a best practice, the script should be located on a disk in cluster storage, or at a highly +available network share, to ensure that it is always accessible to all the cluster nodes. + +```yaml +Type: String +Parameter Sets: DefaultParamSet +Aliases: + +Required: False +Position: Named +Default value: None +Accept pipeline input: False +Accept wildcard characters: False +``` + +### -PreUpdateScript + +Specifies the path and file name for a Windows PowerShell script to run on each node before updating +begins, and before the node is put into Maintenance mode. The file name extension must be `.ps1` and +the total length of the path plus the file name must be no longer than 260 characters. As a best +practice, the script should be located on a disk in cluster storage, or at a highly available +network share, to ensure that the script is always accessible to all the cluster nodes. If a +pre-update script fails, the node isn't updated. + +```yaml +Type: String +Parameter Sets: DefaultParamSet +Aliases: + +Required: False +Position: Named +Default value: None +Accept pipeline input: False +Accept wildcard characters: False +``` + +### -RebootMode + +Specifies the type of reboot to use for each node in the cluster during the update. The available +values are: + +- `ClusProp` +- `FullReboot` +- `SoftReboot` +- `PluginCustomReboot` +- `OrchestratorDefault` + +```yaml +Type: RebootType +Parameter Sets: DefaultParamSet +Aliases: +Accepted values: ClusProp, FullReboot, SoftReboot, PluginCustomReboot, OrchestratorDefault + +Required: False +Position: Named +Default value: None +Accept pipeline input: False +Accept wildcard characters: False +``` + +### -RebootTimeoutMinutes + +Specifies the time in minutes that CAU allows for the restarting of a node. If the restart doesn't +complete within this time, then the Updating Run on that node will be marked as failed. + +```yaml +Type: Int32 +Parameter Sets: DefaultParamSet +Aliases: + +Required: False +Position: Named +Default value: None +Accept pipeline input: False +Accept wildcard characters: False +``` + +### -RunPluginsSerially + +Indicates that CAU will scan each cluster node for applicable updates and stage the updates for each +plug-in in the plug-in order passed into the **CauPluginName** parameter when multiple plug-ins are +used during an Updating Run. By default, CAU scans and stages the applicable updates for all +plug-ins in parallel. Regardless of the configuration of this parameter, CAU installs the applicable +updates for each plug-in sequentially. + +The parameter is valid only when multiple plug-ins are specified for the **CauPluginName** +parameter. If a single plug-in is specified, a warning appears. + +```yaml +Type: SwitchParameter +Parameter Sets: DefaultParamSet +Aliases: + +Required: False +Position: Named +Default value: None +Accept pipeline input: False +Accept wildcard characters: False +``` + +### -StopOnPluginFailure + +Indicates that if a failure occurs during the application of updates on a node by any plug-in, +subsequent updates on the node that are coordinated by the remaining plug-ins are stopped when +multiple plug-ins are used during an Updating Run. By default, a failure by one plug-in doesn't +affect the application of updates on a node by other plug-ins. + +The parameter is valid only when multiple plug-ins are specified for the **CauPluginName** +parameter. If a single plug-in is specified, a warning appears. + +```yaml +Type: SwitchParameter +Parameter Sets: DefaultParamSet +Aliases: + +Required: False +Position: Named +Default value: None +Accept pipeline input: False +Accept wildcard characters: False +``` + +### -Confirm + +Prompts you for confirmation before running the cmdlet. + +```yaml +Type: SwitchParameter +Parameter Sets: (All) +Aliases: cf + +Required: False +Position: Named +Default value: None +Accept pipeline input: False +Accept wildcard characters: False +``` + +### -WhatIf + +Shows what would happen if the cmdlet runs. The cmdlet is not run. + +```yaml +Type: SwitchParameter +Parameter Sets: (All) +Aliases: wi + +Required: False +Position: Named +Default value: None +Accept pipeline input: False +Accept wildcard characters: False +``` + +### CommonParameters + +This cmdlet supports the common parameters: -Debug, -ErrorAction, -ErrorVariable, +-InformationAction, -InformationVariable, -OutVariable, -OutBuffer, -PipelineVariable, -Verbose, +-WarningAction, and -WarningVariable. For more information, see +[about_CommonParameters](/powershell/module/microsoft.powershell.core/about/about_commonparameters). + +## INPUTS + +### None + +## OUTPUTS + +### Microsoft.ClusterAwareUpdating.ActivityIdMap + +### Microsoft.ClusterAwareUpdating.NodeResult + +### Microsoft.ClusterAwareUpdating.NodeStatusNotification + +### Microsoft.ClusterAwareUpdating.UpdateInfo + +### Microsoft.ClusterAwareUpdating.UpdateInstallResult + +### Microsoft.ClusterAwareUpdating.UpdateStagingResult + +## NOTES + +## RELATED LINKS + +[Get-ClusterlessCauRun](get-clusterlesscaurun.md) diff --git a/docset/winserver2025-ps/clusterawareupdating/Save-CauDebugTrace.md b/docset/winserver2025-ps/clusterawareupdating/Save-CauDebugTrace.md index 4cb73b6224..a485e8cd57 100644 --- a/docset/winserver2025-ps/clusterawareupdating/Save-CauDebugTrace.md +++ b/docset/winserver2025-ps/clusterawareupdating/Save-CauDebugTrace.md @@ -2,7 +2,7 @@ description: Use this topic to help manage Windows and Windows Server technologies with Windows PowerShell. external help file: ClusterAwareUpdating.dll-Help.xml Module Name: ClusterAwareUpdating -ms.date: 09/27/2022 +ms.date: 07/01/2024 online version: https://learn.microsoft.com/powershell/module/clusterawareupdating/save-caudebugtrace?view=windowsserver2025-ps&wt.mc_id=ps-gethelp schema: 2.0.0 title: Save-CauDebugTrace @@ -17,7 +17,7 @@ Saves CAU debug tracing information to a local zip file. ``` Save-CauDebugTrace [[-ClusterName] ] [[-FilePath] ] [-Credential ] - [-RunId ] [-Force] [] + [-RunId ] [-Force] [-FeatureUpdateLogs {None | FailedSetup | All}] [] ``` ## DESCRIPTION @@ -38,8 +38,8 @@ Compatibility Mode (HTTP-In)** firewall exception is enabled on each node. Save-CauDebugTrace -ClusterName "CONTOSO-FC1" -FilePath "C:\temp\testrun.zip" ``` -This command saves the debug tracing information for the cluster named CONTOSO-FC1, to a trace file -called `testrun.zip` in the `C:\temp` folder. +This command saves the debug tracing information for the cluster named **CONTOSO-FC1**, to a trace +file called `testrun.zip` in the `C:\temp` folder. ## PARAMETERS @@ -77,6 +77,28 @@ Accept pipeline input: False Accept wildcard characters: False ``` +### -FeatureUpdateLogs + +Specifies the level of detail to include in the debug trace for feature updates. The acceptable +values for this parameter are: + +- `None`: No feature update logs will be included in the debug trace. +- `FailedSetup`: Only logs related to failed feature updates will be included in the debug trace. +- `All`: All feature update logs will be included in the debug trace. + +```yaml +Type: FeatureUpdateLogs +Parameter Sets: (All) +Aliases: +Accepted values: None, FailedSetup, All + +Required: False +Position: Named +Default value: None +Accept pipeline input: False +Accept wildcard characters: False +``` + ### -FilePath Specifies the name of the file to which to save the tracing information, such as `MyTrace.zip`. @@ -131,7 +153,7 @@ Accept wildcard characters: False This cmdlet supports the common parameters: -Debug, -ErrorAction, -ErrorVariable, -InformationAction, -InformationVariable, -OutVariable, -OutBuffer, -PipelineVariable, -Verbose, -WarningAction, and -WarningVariable. For more information, see -[about_CommonParameters](https://go.microsoft.com/fwlink/?LinkID=113216). +[about_CommonParameters](/powershell/module/microsoft.powershell.core/about/about_commonparameters). ## INPUTS @@ -139,11 +161,12 @@ This cmdlet supports the common parameters: -Debug, -ErrorAction, -ErrorVariable ## OUTPUTS -### None +### Microsoft.ClusterAwareUpdating.ActivityIdMap + +### System.IO.FileInfo ## NOTES ## RELATED LINKS -[Invoke-CauRun](./Invoke-CauRun.md) - +[Invoke-CauRun](invoke-caurun.md) diff --git a/docset/winserver2025-ps/clusterawareupdating/Set-CauClusterRole.md b/docset/winserver2025-ps/clusterawareupdating/Set-CauClusterRole.md index 8e48358c3a..1926b424ee 100644 --- a/docset/winserver2025-ps/clusterawareupdating/Set-CauClusterRole.md +++ b/docset/winserver2025-ps/clusterawareupdating/Set-CauClusterRole.md @@ -2,7 +2,7 @@ description: Use this topic to help manage Windows and Windows Server technologies with Windows PowerShell. external help file: ClusterAwareUpdating.dll-Help.xml Module Name: ClusterAwareUpdating -ms.date: 09/27/2022 +ms.date: 07/01/2024 online version: https://learn.microsoft.com/powershell/module/clusterawareupdating/set-cauclusterrole?view=windowsserver2025-ps&wt.mc_id=ps-gethelp schema: 2.0.0 title: Set-CauClusterRole @@ -25,8 +25,11 @@ Set-CauClusterRole [-UseDefault] [-StartDate ] [-DaysOfWeek [-RequireAllNodesOnline] [-WarnAfter ] [-StopAfter ] [-RebootTimeoutMinutes ] [-SeparateReboots] [-RunPluginsSerially] [-StopOnPluginFailure] [-EnableFirewallRules] [-FailbackMode ] [-SuspendClusterNodeTimeoutMinutes ] - [[-ClusterName] ] [[-Credential] ] [-Force] [-WhatIf] [-Confirm] - [] + [-SuspendRetriesPerNode ] [-WaitForStorageRepairTimeoutMinutes ] [-ForcePauseNoDrain] + [-ForcePauseAndDrain] [-ForcePauseDrainAndReboot] [-SkipUpdateChecks] + [-SiteAwareUpdatingOrder ] [-OsRollingUpgrade] [-AttemptSoftReboot] + [-RebootMode ] [[-ClusterName] ] [[-Credential] ] [-Force] + [-WhatIf] [-Confirm] [] ``` ### UpdateNow @@ -53,19 +56,38 @@ Set-CauClusterRole [-UseDefault] [-StartDate ] [-DaysOfWeek [-RequireAllNodesOnline] [-WarnAfter ] [-StopAfter ] [-RebootTimeoutMinutes ] [-SeparateReboots] [-RunPluginsSerially] [-StopOnPluginFailure] [-EnableFirewallRules] [-FailbackMode ] [-SuspendClusterNodeTimeoutMinutes ] - [[-ClusterName] ] [[-Credential] ] [-Force] [-WhatIf] [-Confirm] - [] + [-SuspendRetriesPerNode ] [-WaitForStorageRepairTimeoutMinutes ] [-ForcePauseNoDrain] + [-ForcePauseAndDrain] [-ForcePauseDrainAndReboot] [-SkipUpdateChecks] + [-SiteAwareUpdatingOrder ] [-OsRollingUpgrade] [-AttemptSoftReboot] + [-RebootMode ] [[-ClusterName] ] [[-Credential] ] [-Force] + [-WhatIf] [-Confirm] [] +``` + +### Once + +``` +Set-CauClusterRole [-UseDefault] [-RunOnce] [-CauPluginName ] + [-CauPluginArguments ] [-MaxFailedNodes ] [-MaxRetriesPerNode ] + [-NodeOrder ] [-PreUpdateScript ] [-PostUpdateScript ] + [-ConfigurationName ] [-RequireAllNodesOnline] [-WarnAfter ] + [-StopAfter ] [-RebootTimeoutMinutes ] [-SeparateReboots] [-RunPluginsSerially] + [-StopOnPluginFailure] [-EnableFirewallRules] [-FailbackMode ] + [-SuspendClusterNodeTimeoutMinutes ] [-SuspendRetriesPerNode ] + [-WaitForStorageRepairTimeoutMinutes ] [-ForcePauseNoDrain] [-ForcePauseAndDrain] + [-ForcePauseDrainAndReboot] [-SkipUpdateChecks] [-SiteAwareUpdatingOrder ] + [-OsRollingUpgrade] [-AttemptSoftReboot] [-RebootMode ] [[-ClusterName] ] + [[-Credential] ] [-Force] [-WhatIf] [-Confirm] [] ``` ## DESCRIPTION The `Set-CauClusterRole` cmdlet sets configuration properties for the Cluster-Aware Updating (CAU) clustered role on the specified cluster. This cmdlet can specify properties such as the updating -schedule and updating run parameters. +schedule and Updating Run parameters. -To run this cmdlet with the **PostUpdateScript** or **PreUpdateScript** parameters, Windows PowerShell -remoting must be enabled on each node. To do this, use the `Enable-PSRemoting` cmdlet. In -addition, ensure that the **Windows Remote Management - Compatibility Mode (HTTP-In)** firewall +To run this cmdlet with the **PostUpdateScript** or **PreUpdateScript** parameters, Windows +PowerShell remoting must be enabled on each node. To do this, use the `Enable-PSRemoting` cmdlet. +In addition, ensure that the **Windows Remote Management - Compatibility Mode (HTTP-In)** firewall exception is enabled on each node. ## EXAMPLES @@ -83,17 +105,18 @@ $parameters = @{ Set-CauClusterRole $parameters ``` -This command configures settings for the CAU clustered role on the cluster named CONTOSO-FC1. The -CAU clustered role is configured to perform updating runs on Tuesdays on the first and second weeks -of each month. The CAU clustered role allows 10 minutes for the restarting of each node, if a -restart is necessary. If the restart doesn't complete within this time, then the updating run on -that node is marked as failed. Because the command specifies the **Force** parameter, the cmdlet runs -without displaying confirmation prompts. +This command configures settings for the CAU clustered role on the cluster named **CONTOSO-FC1**. +The CAU clustered role is configured to perform Updating Runs on Tuesdays on the first and second +weeks of each month. The CAU clustered role allows 10 minutes for the restarting of each node, if a +restart is necessary. If the restart doesn't complete within this time, then the Updating Run on +that node is marked as failed. Because the command specifies the **Force** parameter, the cmdlet +runs without displaying confirmation prompts. This example uses splatting to pass parameter values from the `$parameters` variable to the command. Learn more about [Splatting](/powershell/module/microsoft.powershell.core/about/about_splatting). ### Example 2: Configure settings for a CAU cluster role on the specified cluster on the second week of the month + ```powershell $parameters = @{ ClusterName = 'CONTOSO-FC1' @@ -101,7 +124,7 @@ $parameters = @{ WeeksOfMonth = '1,2' IntervalWeeks = '2' RebootTimeoutMinutes = '10' - PostUpdateScript = 'c:\verifyupdatesinstalled.ps1' + PostUpdateScript = 'G:\verifyupdatesinstalled.ps1' Force = $true } Set-CauClusterRole $parameters @@ -119,27 +142,27 @@ DaysOfWeek Tuesday WeeksInterval 2 ``` -This command configures settings for the CAU clustered role on the cluster named CONTOSO-FC1. The -CAU clustered role is configured to perform updating runs on Tuesdays on the second week of each -month. The CAU clustered role allows 10 minutes for the restarting of each node, if a restart is -necessary. If the restart doesn't complete within this time, then the updating run on that node is -marked as failed. The CAU clustered role runs a script after updating completes, just after the node -leaves Maintenance mode. The script is located at the root of drive G: in clustered storage and is -named verifyupdatesinstalled.ps1. Because the command specifies the **Force** parameter, the cmdlet -runs without displaying confirmation prompts. +This command configures settings for the CAU clustered role on the cluster named **CONTOSO-FC1**. +The CAU clustered role is configured to perform Updating Runs on Tuesdays on the second week of +each month. The CAU clustered role allows 10 minutes for the restarting of each node, if a restart +is necessary. If the restart doesn't complete within this time, then the Updating Run on that node +is marked as failed. The CAU clustered role runs a script after updating completes, just after the +node leaves Maintenance mode. The script is located at the root of drive **G:** in clustered +storage and is named `verifyupdatesinstalled.ps1`. Because the command specifies the **Force** +parameter, the cmdlet runs without displaying confirmation prompts. This example uses splatting to pass parameter values from the `$parameters` variable to the command. Learn more about [Splatting](/powershell/module/microsoft.powershell.core/about/about_splatting). -### Example 3: Initiate an updating run on the specified cluster +### Example 3: Initiate an Updating Run on the specified cluster ```powershell Set-CauClusterRole -ClusterName "CONTOSO-FC1" -UpdateNow -Force ``` -This command causes the CAU clustered role to initiate an updating run immediately on the cluster -named CONTOSO-FC1. Because the command specifies the **Force** parameter, the cmdlet runs without -displaying confirmation prompts +This command causes the CAU clustered role to initiate an Updating Run immediately on the cluster +named **CONTOSO-FC1**. Because the command specifies the **Force** parameter, the cmdlet runs +without displaying confirmation prompts. ### Example 4: Configure settings for a CAU cluster role on the specified cluster @@ -156,31 +179,56 @@ $parameters = @{ Set-CauClusterRole @parameters ``` -This example configures settings for the CAU clustered role on the cluster named CONTOSO-FC1. Time -spans are specified for logging a warning or canceling the updating run if it isn't completed. The -earliest date that an updating run can be triggered is 1/1/2012. Because the command specifies the -**Force** parameter, the cmdlet runs without displaying confirmation prompts +This example configures settings for the CAU clustered role on the cluster named **CONTOSO-FC1**. +Time spans are specified for logging a warning or canceling the Updating Run if it isn't completed. +The earliest date that an Updating Run can be triggered is `1/1/2012`. Because the command +specifies the **Force** parameter, the cmdlet runs without displaying confirmation prompts This example uses splatting to pass parameter values from the `$parameters` variable to the command. Learn more about [Splatting](/powershell/module/microsoft.powershell.core/about/about_splatting). ## PARAMETERS +### -AttemptSoftReboot + +Indicates that the CAU clustered role attempts a Kernel Soft Reboot (KSR) for the failover cluster. + +KSR bypasses BIOS/firmware initialization. You can only use KSR for updates that do not require a +BIOS/firmware initialization. + +```yaml +Type: SwitchParameter +Parameter Sets: MonthlyDayOfWeek, Weekly, Once +Aliases: + +Required: False +Position: Named +Default value: None +Accept pipeline input: False +Accept wildcard characters: False +``` + ### -CauPluginArguments Specifies a set of name=value pairs, as arguments, for each updating plug-in to use. + For instance, to specify a Domain argument for one plug-in: + - `@{Domain=Domain.local}` -You can specify multiple pairs in a set separated with semicolons. -For instance: -- `@{name1=value1;name2=value2;name3=value3}` These name=value pairs must be meaningful to the - **CauPluginName** parameter that you specify. If you specify arguments for more than one plug-in, - provide the sets of name=value pairs in the order that you pass values in **CauPluginName**, - separated by commas. For instance: + +You can specify multiple pairs in a set separated with semicolons. For instance: + +- `@{name1=value1;name2=value2;name3=value3}` + +These name=value pairs must be meaningful to the **CauPluginName** parameter that you specify. If +you specify arguments for more than one plug-in, provide the sets of name=value pairs in the order +that you pass values in **CauPluginName**, separated by commas. For instance: + - `@{name1=value1;name2=value2;name3=value3},@{name4=value4;name5=value5}` -For the default **Microsoft.WindowsUpdatePlugin** plug-in, no arguments are needed. -The following arguments are optional: +For the default **Microsoft.WindowsUpdatePlugin** plug-in, no arguments are needed. The following +arguments are optional: + - **'IncludeRecommendedUpdates'='\'**: Boolean value to indicate that recommended updates will be applied in addition to important updates on each node. If not specified, the default value is False. @@ -188,16 +236,19 @@ The following arguments are optional: Agent to filter the updates that will be applied to each node. For a name, use **QueryString** and for a value, enclose the full query in quotation marks. If not specified, then the **Microsoft.WindowsUpdatePlugin** plug-in by default uses the following argument: -- `QueryString="IsInstalled=0 and Type='Software' and IsHidden=0 and IsAssigned=1"` For more - information about query strings for the default **Microsoft.WindowsUpdatePlugin** plug-in and the - criteria such as IsInstalled that can be included in the query strings, see - [IUpdateSearcher::Search method](https://go.microsoft.com/fwlink/p/?LinkId=223304). +- `QueryString="IsInstalled=0 and Type='Software' and IsHidden=0 and IsAssigned=1"` + +For more information about query strings for the default **Microsoft.WindowsUpdatePlugin** plug-in +and the criteria such as IsInstalled that can be included in the query strings, see +[IUpdateSearcher::Search method](/windows/win32/api/wuapi/nf-wuapi-iupdatesearcher-search). For the **Microsoft.HotfixPlugin** plug-in, the following argument is required: + - **HotfixRootFolderPath=\**: The UNC path to a hotfix root folder in an SMB share with a - structure that contains the updates to apply and that contains the hotfix configuration file + structure that contains the updates to apply and that contains the hotfix configuration file. The following arguments are optional for the **Microsoft.HotfixPlugin** plug-in: + - **RequireSmbEncryption=\**: Boolean value to indicate that SMB Encryption will be enforced for accessing data from the SMB share. If not specified, the default value is False. To ensure the integrity of the data accessed from the SMB share, the plug-in requires that the share is enabled @@ -208,13 +259,13 @@ The following arguments are optional for the **Microsoft.HotfixPlugin** plug-in: - **HotfixInstallerTimeoutMinutes=\**: The length of time in minutes that the plug-in allows the hotfix installer process to return. If not specified, the default value is 30 minutes. - **HotfixConfigFileName=\**: Name for the hotfix configuration file. If not specified, the - default name DefaultHotfixConfig.xml is used. For more information about required and optional + default name `DefaultHotfixConfig.xml` is used. For more information about required and optional arguments for the **Microsoft.HotfixPlugin** plug-in, see - [How CAU Plug-ins Work](https://go.microsoft.com/fwlink/p/?LinkId=235333). + [How Cluster-Aware Updating plug-ins work](/windows-server/failover-clustering/cluster-aware-updating-plug-ins). ```yaml Type: Hashtable[] -Parameter Sets: MonthlyDayOfWeek, Weekly +Parameter Sets: MonthlyDayOfWeek, Weekly, Once Aliases: Required: False @@ -227,15 +278,15 @@ Accept wildcard characters: False ### -CauPluginName Specifies one or more plug-ins to use when performing scans or updates. You can specify multiple -values separated with commas. The default is the Microsoft.WindowsUpdatePlugin plug-in. This plug-in -coordinates the Windows Update Agent software resident on each cluster node, the same software that -is used when updates are downloaded from Windows Update or Microsoft Update, or from a Windows -Server Update Services (WSUS) server. For more information about how plug-ins work with CAU, see -[How CAU Plug-ins Work](https://go.microsoft.com/fwlink/p/?LinkId=235333). +values separated with commas. The default is the **Microsoft.WindowsUpdatePlugin** plug-in. This +plug-in coordinates the Windows Update Agent software resident on each cluster node, the same +software that is used when updates are downloaded from Windows Update or Microsoft Update, or from +a Windows Server Update Services (WSUS) server. For more information about how plug-ins work with +CAU, see [How Cluster-Aware Updating plug-ins work](/windows-server/failover-clustering/cluster-aware-updating-plug-ins). ```yaml Type: String[] -Parameter Sets: MonthlyDayOfWeek, Weekly +Parameter Sets: MonthlyDayOfWeek, Weekly, Once Aliases: Required: False @@ -267,14 +318,14 @@ Accept wildcard characters: False ### -ConfigurationName Specifies the Windows PowerShell session configuration that defines the session in which scripts, -specified by the **PreUpdateScript** and **PostUpdateScript** parameters, and cmdlets are run, and can -limit the cmdlets that are available to be run. If either a pre-update or post-update script is +specified by the **PreUpdateScript** and **PostUpdateScript** parameters, and cmdlets are run, and +can limit the cmdlets that are available to be run. If either a pre-update or post-update script is specified but a configuration name isn't specified, then the default session configuration that is built into Windows PowerShell is used. ```yaml Type: String -Parameter Sets: MonthlyDayOfWeek, Weekly +Parameter Sets: MonthlyDayOfWeek, Weekly, Once Aliases: Required: False @@ -284,22 +335,6 @@ Accept pipeline input: False Accept wildcard characters: False ``` -### -Confirm - -Prompts you for confirmation before running the cmdlet. - -```yaml -Type: SwitchParameter -Parameter Sets: (All) -Aliases: cf - -Required: False -Position: Named -Default value: False -Accept pipeline input: False -Accept wildcard characters: False -``` - ### -Credential Specifies the administrative credentials for the target cluster. @@ -318,8 +353,8 @@ Accept wildcard characters: False ### -DaysOfWeek -Specifies the days of the week on which the task will be triggered. -Multiple values can be specified either separated with commas or as a hexadecimal sum. +Specifies the days of the week on which the task will be triggered. Multiple values can be +specified either separated with commas or as a hexadecimal sum. - **Sunday:** (0x01) - **Monday:** (0x02) @@ -329,11 +364,6 @@ Multiple values can be specified either separated with commas or as a hexadecima - **Friday:** (0x20) - **Saturday:** (0x40) -**Examples:** -- **-DaysOfWeek:** Monday, Wednesday, Friday -- **-DaysOfWeek:** 0x02, 0x08, 0x20 -- **-DaysOfWeek:** 0x2A - ```yaml Type: Weekdays Parameter Sets: MonthlyDayOfWeek, Weekly @@ -353,13 +383,13 @@ Indicates that this cmdlet enables the **Remote Shutdown** Windows Firewall rule cluster node, if it isn't already enabled, each time the CAU clustered role performs an Updating Run. Enabling this rule group permits inbound communication to each cluster node during each Updating Run that allows CAU to shut down and restart the node remotely. If Windows Firewall is in -use on the cluster nodes and the rule group isn't enabled, the updating run will fail. The **Remote +use on the cluster nodes and the rule group isn't enabled, the Updating Run will fail. The **Remote Shutdown** Windows Firewall rule group isn't enabled when it will conflict with Group Policy settings that are configured for Windows Firewall. ```yaml Type: SwitchParameter -Parameter Sets: MonthlyDayOfWeek, Weekly +Parameter Sets: MonthlyDayOfWeek, Weekly, Once Aliases: Required: False @@ -375,14 +405,15 @@ Specifies the method used to bring drained workloads back to the node, at the en node. Drained workloads are workloads that were previously running on the node, but were moved to another node. The acceptable values for this parameter are: -- NoFailback -- Immediate -- Policy - The default value is Immediate. +- `NoFailback` +- `Immediate` +- `Policy` + +The default value is `Immediate`. ```yaml Type: FailbackType -Parameter Sets: MonthlyDayOfWeek, Weekly +Parameter Sets: MonthlyDayOfWeek, Weekly, Once Aliases: Accepted values: NoFailback, Immediate, Policy @@ -409,11 +440,64 @@ Accept pipeline input: False Accept wildcard characters: False ``` +### -ForcePauseAndDrain + +Indicates that the CAU cluster role forces cluster nodes to pause and drain roles. + +A forced drain moves the roles off of the draining node even if the group cannot move. A group +might not be able to move because no other node can host the group or the group is locked. + +```yaml +Type: SwitchParameter +Parameter Sets: MonthlyDayOfWeek, Weekly, Once +Aliases: + +Required: False +Position: Named +Default value: None +Accept pipeline input: False +Accept wildcard characters: False +``` + +### -ForcePauseDrainAndReboot + +Indicates that the CAU cluster role forces cluster nodes to pause, drain roles, and restart. + +A forced drain moves the roles off of the draining node even if the group cannot move. A group +might not be able to move because no other node can host the group or the group is locked. + +```yaml +Type: SwitchParameter +Parameter Sets: MonthlyDayOfWeek, Weekly, Once +Aliases: + +Required: False +Position: Named +Default value: None +Accept pipeline input: False +Accept wildcard characters: False +``` + +### -ForcePauseNoDrain + +Indicates that the CAU cluster role forces cluster nodes to pause. The nodes are not drained. + +```yaml +Type: SwitchParameter +Parameter Sets: MonthlyDayOfWeek, Weekly, Once +Aliases: + +Required: False +Position: Named +Default value: None +Accept pipeline input: False +Accept wildcard characters: False +``` + ### -IntervalWeeks -Specifies the interval between weeks when the task will be triggered. -An interval of 1 produces a weekly schedule. -An interval of 2 produces an every-other week schedule. +Specifies the interval between weeks when the task will be triggered. An interval of 1 produces a +weekly schedule. An interval of 2 produces an every-other week schedule. ```yaml Type: Int32 @@ -429,14 +513,13 @@ Accept wildcard characters: False ### -MaxFailedNodes -Specifies the maximum number of nodes on which updating can fail. -If one more than this number of nodes fails, then the Updating Run is stopped. -The range is from 0 through 1 less than the number of cluster nodes. -The default for most clusters is approximately one-third of the number of nodes. +Specifies the maximum number of nodes on which updating can fail. If one more than this number of +nodes fails, then the Updating Run is stopped. The range is from 0 through 1 less than the number +of cluster nodes. The default for most clusters is approximately one-third of the number of nodes. ```yaml Type: Int32 -Parameter Sets: MonthlyDayOfWeek, Weekly +Parameter Sets: MonthlyDayOfWeek, Weekly, Once Aliases: Required: False @@ -449,11 +532,11 @@ Accept wildcard characters: False ### -MaxRetriesPerNode Specifies the maximum number of times that the update process, which includes any pre-update and -post-update scripts, is retried per node. The maximum is 64and the default is 3. +post-update scripts, is retried per node. The maximum is 64 and the default is 3. ```yaml Type: Int32 -Parameter Sets: MonthlyDayOfWeek, Weekly +Parameter Sets: MonthlyDayOfWeek, Weekly, Once Aliases: Required: False @@ -469,7 +552,24 @@ Specifies an array of cluster node names in the order that they should be update ```yaml Type: String[] -Parameter Sets: MonthlyDayOfWeek, Weekly +Parameter Sets: MonthlyDayOfWeek, Weekly, Once +Aliases: + +Required: False +Position: Named +Default value: None +Accept pipeline input: False +Accept wildcard characters: False +``` + +### -OsRollingUpgrade + +Indicates that the CAU cluster role upgrades the operating system of the cluster nodes without +stopping the Hyper-V or the Scale-Out File Server workloads. + +```yaml +Type: SwitchParameter +Parameter Sets: MonthlyDayOfWeek, Weekly, Once Aliases: Required: False @@ -482,14 +582,14 @@ Accept wildcard characters: False ### -PostUpdateScript Specifies the path and file name for a Windows PowerShell script to run after updating completes, -just after the node leaves Maintenance mode. The file name extension must be .ps1 and the total +just after the node leaves Maintenance mode. The file name extension must be `.ps1` and the total length of the path plus the file name must be no longer than 260 characters. As a best practice, the script should be located on a disk in cluster storage, to ensure that it is always accessible to all the cluster nodes. ```yaml Type: String -Parameter Sets: MonthlyDayOfWeek, Weekly +Parameter Sets: MonthlyDayOfWeek, Weekly, Once Aliases: Required: False @@ -502,15 +602,39 @@ Accept wildcard characters: False ### -PreUpdateScript Specifies the path and file name for a Windows PowerShell script to run on each node before updating -begins, and before the node is put into Maintenance mode. The file name extension must be .ps1 and +begins, and before the node is put into Maintenance mode. The file name extension must be `.ps1` and the total length of the path plus the file name must be no longer than 260 characters. As a best practice, the script should be located on a disk in cluster storage, to ensure that it is always accessible to all the cluster nodes. ```yaml Type: String -Parameter Sets: MonthlyDayOfWeek, Weekly +Parameter Sets: MonthlyDayOfWeek, Weekly, Once +Aliases: + +Required: False +Position: Named +Default value: None +Accept pipeline input: False +Accept wildcard characters: False +``` + +### -RebootMode + +Specifies the type of reboot to use for each node in the cluster during the update. The available +values are: + +- `ClusProp` +- `FullReboot` +- `SoftReboot` +- `PluginCustomReboot` +- `OrchestratorDefault` + +```yaml +Type: RebootType +Parameter Sets: MonthlyDayOfWeek, Weekly, Once Aliases: +Accepted values: ClusProp, FullReboot, SoftReboot, PluginCustomReboot, OrchestratorDefault Required: False Position: Named @@ -521,12 +645,12 @@ Accept wildcard characters: False ### -RebootTimeoutMinutes -Specifies the time in minutes that CAU will allow for the restarting of a node. If the restart doesn't -complete within this time, then the updating run on that node is marked as failed. +Specifies the time in minutes that CAU will allow for the restarting of a node. If the restart +doesn't complete within this time, then the Updating Run on that node is marked as failed. ```yaml Type: Int32 -Parameter Sets: MonthlyDayOfWeek, Weekly +Parameter Sets: MonthlyDayOfWeek, Weekly, Once Aliases: Required: False @@ -542,7 +666,24 @@ Indicates that all cluster nodes must be online and reachable before updating be ```yaml Type: SwitchParameter -Parameter Sets: MonthlyDayOfWeek, Weekly +Parameter Sets: MonthlyDayOfWeek, Weekly, Once +Aliases: + +Required: False +Position: Named +Default value: None +Accept pipeline input: False +Accept wildcard characters: False +``` + +### -RunOnce + +Specifies that the CAU run should only be performed once, rather than on a recurring schedule. This +can be useful if you only need to perform a one-time update of your cluster nodes. + +```yaml +Type: SwitchParameter +Parameter Sets: Once Aliases: Required: False @@ -555,19 +696,19 @@ Accept wildcard characters: False ### -RunPluginsSerially Indicates that CAU scans each cluster node for applicable updates and stage the updates for each -plug-in in the plug-in order passed into the*CauPluginName* parameter, when multiple plug-ins are -used during an updating run. +plug-in in the plug-in order passed into the **CauPluginName** parameter, when multiple plug-ins are +used during an Updating Run. By default, CAU scans and stages the applicable updates for all plug-ins in parallel. Regardless of the configuration of this parameter, CAU installs the applicable updates for each plug-in sequentially. -The parameter is valid only when multiple plug-ins are specified in the **CauPluginName** parameter. If a -single plug-in is specified, a warning appears. +The parameter is valid only when multiple plug-ins are specified in the **CauPluginName** +parameter. If a single plug-in is specified, a warning appears. ```yaml Type: SwitchParameter -Parameter Sets: MonthlyDayOfWeek, Weekly +Parameter Sets: MonthlyDayOfWeek, Weekly, Once Aliases: Required: False @@ -582,14 +723,30 @@ Accept wildcard characters: False Indicates that CAU shuts down and restart a cluster node after each plug-in installs updates on the node, if the installation of an update by a plug-in requires a restart that CAU will shut down and restart a cluster node after each plug-in installs updates on the node, if the installation of an -update by a plug-in requires a restart +update by a plug-in requires a restart. The parameter is valid only when multiple plug-ins are specified in the **CauPluginName** parameter. If a single plug-in is specified, a warning appears. +```yaml +Type: String[] +Parameter Sets: MonthlyDayOfWeek, Weekly, Once +Aliases: + +Required: False +Position: Named +Default value: None +Accept pipeline input: False +Accept wildcard characters: False +``` + +### -SkipUpdateChecks + +Indicates that the CAU cluster role skips update checks. + ```yaml Type: SwitchParameter -Parameter Sets: MonthlyDayOfWeek, Weekly +Parameter Sets: MonthlyDayOfWeek, Weekly, Once Aliases: Required: False @@ -601,7 +758,7 @@ Accept wildcard characters: False ### -StartDate -Specifies the earliest date on which the updating run can be triggered. +Specifies the earliest date on which the Updating Run can be triggered. ```yaml Type: DateTime @@ -617,9 +774,9 @@ Accept wildcard characters: False ### -StopAfter -Specifies the time in minutes after which the updating run is canceled if it hasn't completed. The +Specifies the time in minutes after which the Updating Run is canceled if it hasn't completed. The time span can be expressed in the standard ways available in Windows PowerShell, for instance, -`01:30:00` represents one hour and thirty minutes. By default, the updating run is allowed an +`01:30:00` represents one hour and thirty minutes. By default, the Updating Run is allowed an unlimited amount of time to complete. If pre-update or post-update scripts are specified, then the entire process of running scripts and @@ -627,7 +784,7 @@ performing updates must be complete within this time limit. ```yaml Type: TimeSpan -Parameter Sets: MonthlyDayOfWeek, Weekly +Parameter Sets: MonthlyDayOfWeek, Weekly, Once Aliases: Required: False @@ -641,14 +798,14 @@ Accept wildcard characters: False Indicates that if a failure occurs during the application of updates on a node by any plug-in, subsequent updates on the node that are coordinated by the remaining plug-ins are stopped when -multiple plug-ins are used during an updating run. +multiple plug-ins are used during an Updating Run. -The parameter is valid only when multiple plug-ins are specified for the **CauPluginName** parameter. -If a single plug-in is specified, a warning appears. +The parameter is valid only when multiple plug-ins are specified for the **CauPluginName** +parameter. If a single plug-in is specified, a warning appears. ```yaml Type: SwitchParameter -Parameter Sets: MonthlyDayOfWeek, Weekly +Parameter Sets: MonthlyDayOfWeek, Weekly, Once Aliases: Required: False @@ -660,8 +817,8 @@ Accept wildcard characters: False ### -SuspendClusterNodeTimeoutMinutes -Specifies the maximum amount of time CAU should wait for the `Suspend-ClusterNode` cmdlet to succeed if -the underlying clustered space is in degraded condition. +Specifies the maximum amount of time CAU should wait for the `Suspend-ClusterNode` cmdlet to +succeed if the underlying clustered space is in degraded condition. If `Suspend-ClusterNode` fails with ERROR_CLUSTER_SPACE_DEGRADED error, CAU will keep retrying for **SuspendClusterNodeTimeoutMinutes** or suspend the call if the command succeeds. @@ -673,7 +830,23 @@ for this value for every node in the cluster in the worst case. ```yaml Type: Int32 -Parameter Sets: MonthlyDayOfWeek, Weekly +Parameter Sets: MonthlyDayOfWeek, Weekly, Once +Aliases: + +Required: False +Position: Named +Default value: None +Accept pipeline input: False +Accept wildcard characters: False +``` + +### -SuspendRetriesPerNode + +Specifies the number of times to retry suspending a node before moving on to the next node. + +```yaml +Type: Int32 +Parameter Sets: MonthlyDayOfWeek, Weekly, Once Aliases: Required: False @@ -685,7 +858,7 @@ Accept wildcard characters: False ### -UpdateNow -Instructs the CAU clustered role to immediately initiate an updating run using the configured +Instructs the CAU clustered role to immediately initiate an Updating Run using the configured settings. ```yaml @@ -706,7 +879,24 @@ Indicates that default values are used for all parameters that don't have specif ```yaml Type: SwitchParameter -Parameter Sets: MonthlyDayOfWeek, UseDefault, Weekly +Parameter Sets: MonthlyDayOfWeek, UseDefault, Weekly, Once +Aliases: + +Required: False +Position: Named +Default value: None +Accept pipeline input: False +Accept wildcard characters: False +``` + +### -WaitForStorageRepairTimeoutMinutes + +Specifies the amount of time in minutes to wait for storage to be repaired on a node before +continuing with an update. + +```yaml +Type: Int32 +Parameter Sets: MonthlyDayOfWeek, Weekly, Once Aliases: Required: False @@ -718,13 +908,13 @@ Accept wildcard characters: False ### -WarnAfter -Specifies the time in minutes after which a warning is logged if the updating run, including any +Specifies the time in minutes after which a warning is logged if the Updating Run, including any pre-update and post-update scripts, hasn't completed. By default, no warning is logged, regardless -of the time taken by the updating run. +of the time taken by the Updating Run. ```yaml Type: TimeSpan -Parameter Sets: MonthlyDayOfWeek, Weekly +Parameter Sets: MonthlyDayOfWeek, Weekly, Once Aliases: Required: False @@ -736,8 +926,8 @@ Accept wildcard characters: False ### -WeeksOfMonth -Specifies the weeks of the month when the Updating Run should be run. -The value 5 represents the last week of the month. +Specifies the weeks of the month when the Updating Run should be run. The value 5 represents the +last week of the month. ```yaml Type: Int32[] @@ -751,10 +941,25 @@ Accept pipeline input: False Accept wildcard characters: False ``` +### -Confirm + +Prompts you for confirmation before running the cmdlet. + +```yaml +Type: SwitchParameter +Parameter Sets: (All) +Aliases: cf + +Required: False +Position: Named +Default value: None +Accept pipeline input: False +Accept wildcard characters: False +``` + ### -WhatIf -Shows what would happen if the cmdlet runs. -The cmdlet isn't run. +Shows what would happen if the cmdlet runs. The cmdlet is not run. ```yaml Type: SwitchParameter @@ -763,7 +968,7 @@ Aliases: wi Required: False Position: Named -Default value: False +Default value: None Accept pipeline input: False Accept wildcard characters: False ``` @@ -773,7 +978,7 @@ Accept wildcard characters: False This cmdlet supports the common parameters: -Debug, -ErrorAction, -ErrorVariable, -InformationAction, -InformationVariable, -OutVariable, -OutBuffer, -PipelineVariable, -Verbose, -WarningAction, and -WarningVariable. For more information, see -[about_CommonParameters](https://go.microsoft.com/fwlink/?LinkID=113216). +[about_CommonParameters](/powershell/module/microsoft.powershell.core/about/about_commonparameters). ## INPUTS @@ -781,19 +986,18 @@ This cmdlet supports the common parameters: -Debug, -ErrorAction, -ErrorVariable ## OUTPUTS -### None +### System.Object ## NOTES ## RELATED LINKS -[Add-CauClusterRole](./Add-CauClusterRole.md) - -[Disable-CauClusterRole](./Disable-CauClusterRole.md) +[Add-CauClusterRole](add-cauclusterrole.md) -[Enable-CauClusterRole](./Enable-CauClusterRole.md) +[Disable-CauClusterRole](disable-cauclusterrole.md) -[Get-CauClusterRole](./Get-CauClusterRole.md) +[Enable-CauClusterRole](enable-cauclusterrole.md) -[Remove-CauClusterRole](./Remove-CauClusterRole.md) +[Get-CauClusterRole](get-cauclusterrole.md) +[Remove-CauClusterRole](remove-cauclusterrole.md) diff --git a/docset/winserver2025-ps/failoverclusters/Add-ClusterExcludedAdapter.md b/docset/winserver2025-ps/failoverclusters/Add-ClusterExcludedAdapter.md new file mode 100644 index 0000000000..a8b2c62334 --- /dev/null +++ b/docset/winserver2025-ps/failoverclusters/Add-ClusterExcludedAdapter.md @@ -0,0 +1,167 @@ +--- +description: Use this topic to help manage Windows and Windows Server technologies with Windows PowerShell. +external help file: Microsoft.FailoverClusters.PowerShell.dll-Help.xml +Module Name: FailoverClusters +ms.date: 08/28/2024 +online version: https://learn.microsoft.com/powershell/module/failoverclusters/add-clusterexcludedadapter?view=windowsserver2025-ps&wt.mc_id=ps-gethelp +schema: 2.0.0 +title: Add-ClusterExcludedAdapter +--- + +# Add-ClusterExcludedAdapter + +## SYNOPSIS +Adds a network adapter to the list of excluded adapters. + +## SYNTAX + +``` +Add-ClusterExcludedAdapter -ExclusionType -ExclusionValue + [-CimSession ] [-ThrottleLimit ] [-AsJob] [] +``` + +## DESCRIPTION + +The `Add-ClusterExcludedAdapter` cmdlet adds a network adapter to a list of network adapters that +should be excluded from use by the Failover Cluster. By default, the cluster will use all available +network adapters, but in some cases you may want to reserve certain adapters as backup or +management, such as Dell iDRAC or HPE iLO. + +## EXAMPLES + +### Example 1 + +```powershell +Add-ClusterExcludedAdapter -ExclusionType "IPPrefix" -ExclusionValue "10.10.20.25" +``` + +This example excludes the network adapter based on the IP Address `10.10.20.25` from use by the +cluster. + +## PARAMETERS + +### -AsJob + +Runs the cmdlet as a background job. Use this parameter to run commands that take a long time to +complete. + +The cmdlet immediately returns an object that represents the job and then displays the command +prompt. You can continue to work in the session while the job completes. + +For more information about Windows PowerShell background jobs, see +[about_Jobs](/powershell/module/microsoft.powershell.core/about/about_jobs). + +```yaml +Type: SwitchParameter +Parameter Sets: (All) +Aliases: + +Required: False +Position: Named +Default value: None +Accept pipeline input: False +Accept wildcard characters: False +``` + +### -CimSession + +Runs the cmdlet in a remote session or on a remote computer. Enter a computer name or a session +object, such as the output of a [New-CimSession](/powershell/module/cimcmdlets/new-cimsession) +or [Get-CimSession](/powershell/module/cimcmdlets/get-cimsession) cmdlet. The default is the +current session on the local computer. + +```yaml +Type: CimSession[] +Parameter Sets: (All) +Aliases: Session + +Required: False +Position: Named +Default value: None +Accept pipeline input: False +Accept wildcard characters: False +``` + +### -ExclusionType + +Specifies the type of exclusion to add to the cluster. Acceptable values are: + +- `IPPrefix`: Excludes a network adapter based on its IP address. +- `Description`: Excludes a network adapter based on its description. +- `FriendlyName`: Excludes a network adapter based on its friendly name. + +```yaml +Type: AdapterExclusionType +Parameter Sets: (All) +Aliases: +Accepted values: IPPrefix, Description, FriendlyName + +Required: True +Position: Named +Default value: None +Accept pipeline input: False +Accept wildcard characters: False +``` + +### -ExclusionValue + +Specifies the value to use for the exclusion. The value of this parameter depends on the value of +the `-ExclusionType` parameter. + +```yaml +Type: String[] +Parameter Sets: (All) +Aliases: + +Required: True +Position: Named +Default value: None +Accept pipeline input: False +Accept wildcard characters: False +``` + +### -ThrottleLimit + +Specifies the maximum number of concurrent operations that can be established to run the cmdlet. If +this parameter is omitted or a value of `0` is entered, then PowerShell calculates an optimum +throttle limit for the cmdlet based on the number of CIM cmdlets that are running on the computer. +The throttle limit applies only to the current cmdlet, not to the session or to the computer. + +```yaml +Type: Int32 +Parameter Sets: (All) +Aliases: + +Required: False +Position: Named +Default value: None +Accept pipeline input: False +Accept wildcard characters: False +``` + +### CommonParameters + +This cmdlet supports the common parameters: -Debug, -ErrorAction, -ErrorVariable, +-InformationAction, -InformationVariable, -OutVariable, -OutBuffer, -PipelineVariable, -Verbose, +-WarningAction, and -WarningVariable. For more information, see +[about_CommonParameters](/powershell/module/microsoft.powershell.core/about/about_commonparameters). + +## INPUTS + +### None + +## OUTPUTS + +### System.Object + +## NOTES + +## RELATED LINKS + +[Get-ClusterExcludedAdapter](get-clusterexcludedadapter.md) + +[Remove-ClusterExcludedAdapter](remove-clusterexcludedadapter.md) + +[Repair-ClusterNameAccount](repair-clusternameaccount.md) + +[Set-ClusterExcludedAdapter](set-clusterexcludedadapter.md) diff --git a/docset/winserver2025-ps/failoverclusters/Add-WorkgroupClusterNode.md b/docset/winserver2025-ps/failoverclusters/Add-WorkgroupClusterNode.md new file mode 100644 index 0000000000..501c03b6b4 --- /dev/null +++ b/docset/winserver2025-ps/failoverclusters/Add-WorkgroupClusterNode.md @@ -0,0 +1,182 @@ +--- +description: Use this topic to help manage Windows and Windows Server technologies with Windows PowerShell. +external help file: Microsoft.FailoverClusters.Adless.PowerShell.psm1-help.xml +Module Name: FailoverClusters +ms.date: 09/11/2024 +online version: https://learn.microsoft.com/powershell/module/failoverclusters/add-workgroupclusternode?view=windowsserver2025-ps&wt.mc_id=ps-gethelp +schema: 2.0.0 +title: Add-WorkgroupClusterNode +--- + +# Add-WorkgroupClusterNode + +## SYNOPSIS +Adds a node to a workgroup cluster. + +## SYNTAX + +``` +Add-WorkgroupClusterNode [-Node] [-Credentials] [-Name] + [-Credential] [-NoStorage] [-Confirm] [-WhatIf] [] +``` + +## DESCRIPTION + +The `Add-WorkgroupClusterNode` cmdlet adds a node to a workgroup cluster. + +## EXAMPLES + +### EXAMPLE 1 + +```powershell +$params = @{ + Node = @("Node1", "Node2") + Credentials = @($cred1, $cred2) + Name = "Node3" + Credential = $cred3 +} +Add-WorkgroupClusterNode @params +``` + +This example adds `Node3` to the cluster whose membership is comprised of `Node1` and `Node2`. + +## PARAMETERS + +### -Node + +An array of nodes to be added to the cluster. + +```yaml +Type: String[] +Parameter Sets: (All) +Aliases: + +Required: True +Position: 1 +Default value: None +Accept pipeline input: False +Accept wildcard characters: False +``` + +### -Credentials + +An array of credentials for the nodes. + +```yaml +Type: PSCredential[] +Parameter Sets: (All) +Aliases: + +Required: True +Position: 2 +Default value: None +Accept pipeline input: False +Accept wildcard characters: False +``` + +### -Name + +The name of the node to be added. + +```yaml +Type: String +Parameter Sets: (All) +Aliases: + +Required: True +Position: 3 +Default value: None +Accept pipeline input: False +Accept wildcard characters: False +``` + +### -Credential + +The credential for the node to be added. + +```yaml +Type: PSCredential +Parameter Sets: (All) +Aliases: + +Required: True +Position: 4 +Default value: None +Accept pipeline input: False +Accept wildcard characters: False +``` + +### -NoStorage + +Specifies that shared storage is ignored for the workgroup cluster node. + +```yaml +Type: SwitchParameter +Parameter Sets: (All) +Aliases: + +Required: False +Position: Named +Default value: False +Accept pipeline input: False +Accept wildcard characters: False +``` + +### -Confirm + +Prompts you for confirmation before running the cmdlet. + +```yaml +Type: SwitchParameter +Parameter Sets: (All) +Aliases: + +Required: False +Position: Named +Default value: False +Accept pipeline input: False +Accept wildcard characters: False +``` + +### -WhatIf + +Shows what would happen if the cmdlet runs. The cmdlet isn't run. + +```yaml +Type: SwitchParameter +Parameter Sets: (All) +Aliases: + +Required: False +Position: Named +Default value: False +Accept pipeline input: False +Accept wildcard characters: False +``` + +### CommonParameters + +This cmdlet supports the common parameters: -Debug, -ErrorAction, -ErrorVariable, +-InformationAction, -InformationVariable, -OutVariable, -OutBuffer, -PipelineVariable, -Verbose, +-WarningAction, and -WarningVariable. For more information, see +[about_CommonParameters](/powershell/module/microsoft.powershell.core/about/about_commonparameters). + +## INPUTS + +## OUTPUTS + +## NOTES + +## RELATED LINKS + +[New-WorkgroupCluster](new-workgroupcluster.md) + +[Remove-WorkgroupCluster](remove-workgroupcluster.md) + +[Remove-WorkgroupClusterNode](remove-workgroupclusternode.md) + +[Set-WorkgroupClusterRemotingConfiguration](set-workgroupclusterremotingconfiguration.md) + +[Test-WorkgroupCluster](test-workgroupcluster.md) + +[Test-WorkgroupClusterRemoting](test-workgroupclusterremoting.md) diff --git a/docset/winserver2025-ps/failoverclusters/Get-ClusterCredential.md b/docset/winserver2025-ps/failoverclusters/Get-ClusterCredential.md new file mode 100644 index 0000000000..e3548d6064 --- /dev/null +++ b/docset/winserver2025-ps/failoverclusters/Get-ClusterCredential.md @@ -0,0 +1,72 @@ +--- +description: Use this topic to help manage Windows and Windows Server technologies with Windows PowerShell. +external help file: Microsoft.FailoverClusters.PowerShell.dll-Help.xml +Module Name: FailoverClusters +ms.date: 09/17/2024 +online version: https://learn.microsoft.com/powershell/module/failoverclusters/get-clustercredential?view=windowsserver2025-ps&wt.mc_id=ps-gethelp +schema: 2.0.0 +title: Get-ClusterCredential +--- + +# Get-ClusterCredential + +## SYNOPSIS +Retrieves the credentials for a specified node in a failover cluster. + +## SYNTAX + +``` +Get-ClusterCredential [[-NodeName] ] [] +``` + +## DESCRIPTION + +The `Get-ClusterCredential` cmdlet retrieves the credentials for a specified node in a failover +cluster. + +## EXAMPLES + +### Example 1 + +```powershell +Get-ClusterCredential -NodeName "Node01" +``` + +This example retrieves the credentials for a node named `Node01` in the failover cluster. + +## PARAMETERS + +### -NodeName + +Specifies the name of the node for which to retrieve the credentials. + +```yaml +Type: String +Parameter Sets: (All) +Aliases: + +Required: False +Position: 0 +Default value: None +Accept pipeline input: False +Accept wildcard characters: False +``` + +### CommonParameters + +This cmdlet supports the common parameters: -Debug, -ErrorAction, -ErrorVariable, +-InformationAction, -InformationVariable, -OutVariable, -OutBuffer, -PipelineVariable, -Verbose, +-WarningAction, and -WarningVariable. For more information, see +[about_CommonParameters](/powershell/module/microsoft.powershell.core/about/about_commonparameters). + +## INPUTS + +### None + +## OUTPUTS + +### System.Management.Automation.PSCredential + +## NOTES + +## RELATED LINKS diff --git a/docset/winserver2025-ps/failoverclusters/Get-ClusterExcludedAdapter.md b/docset/winserver2025-ps/failoverclusters/Get-ClusterExcludedAdapter.md new file mode 100644 index 0000000000..a04d02e84d --- /dev/null +++ b/docset/winserver2025-ps/failoverclusters/Get-ClusterExcludedAdapter.md @@ -0,0 +1,150 @@ +--- +description: Use this topic to help manage Windows and Windows Server technologies with Windows PowerShell. +external help file: Microsoft.FailoverClusters.PowerShell.dll-Help.xml +Module Name: FailoverClusters +ms.date: 08/28/2024 +online version: https://learn.microsoft.com/powershell/module/failoverclusters/get-clusterexcludedadapter?view=windowsserver2025-ps&wt.mc_id=ps-gethelp +schema: 2.0.0 +title: Get-ClusterExcludedAdapter +--- + +# Get-ClusterExcludedAdapter + +## SYNOPSIS +Retrieves a network adapter from the list of excluded adapters. + +## SYNTAX + +``` +Get-ClusterExcludedAdapter -ExclusionType [-CimSession ] + [-ThrottleLimit ] [-AsJob] [] +``` + +## DESCRIPTION + +The `Get-ClusterExcludedAdapter` cmdlet retrieves a network adapter from a list of network adapters +that should be excluded from use by the Failover Cluster. By default, the cluster will use all +available network adapters, but in some cases you may want to reserve certain adapters as backup or +management, such as Dell iDRAC or HPE iLO. + +## EXAMPLES + +### Example 1 + +```powershell +Get-ClusterExcludedAdapter -ExclusionType "FriendlyName" +``` + +This example retrieves a list of network adapters that have been excluded from use by the cluster +based on the friendly name. + +## PARAMETERS + +### -AsJob + +Runs the cmdlet as a background job. Use this parameter to run commands that take a long time to +complete. + +The cmdlet immediately returns an object that represents the job and then displays the command +prompt. You can continue to work in the session while the job completes. + +For more information about Windows PowerShell background jobs, see +[about_Jobs](/powershell/module/microsoft.powershell.core/about/about_jobs). + +```yaml +Type: SwitchParameter +Parameter Sets: (All) +Aliases: + +Required: False +Position: Named +Default value: None +Accept pipeline input: False +Accept wildcard characters: False +``` + +### -CimSession + +Runs the cmdlet in a remote session or on a remote computer. Enter a computer name or a session +object, such as the output of a [New-CimSession](/powershell/module/cimcmdlets/new-cimsession) +or [Get-CimSession](/powershell/module/cimcmdlets/get-cimsession) cmdlet. The default is the +current session on the local computer. + +```yaml +Type: CimSession[] +Parameter Sets: (All) +Aliases: Session + +Required: False +Position: Named +Default value: None +Accept pipeline input: False +Accept wildcard characters: False +``` + +### -ExclusionType + +Specifies the type of exclusion to retrieve from the cluster. Acceptable values are: + +- `IPPrefix`: Excludes a network adapter based on its IP address. +- `Description`: Excludes a network adapter based on its description. +- `FriendlyName`: Excludes a network adapter based on its friendly name. + +```yaml +Type: AdapterExclusionType +Parameter Sets: (All) +Aliases: +Accepted values: IPPrefix, Description, FriendlyName + +Required: True +Position: Named +Default value: None +Accept pipeline input: False +Accept wildcard characters: False +``` + +### -ThrottleLimit + +Specifies the maximum number of concurrent operations that can be established to run the cmdlet. If +this parameter is omitted or a value of `0` is entered, then PowerShell calculates an optimum +throttle limit for the cmdlet based on the number of CIM cmdlets that are running on the computer. +The throttle limit applies only to the current cmdlet, not to the session or to the computer. + +```yaml +Type: Int32 +Parameter Sets: (All) +Aliases: + +Required: False +Position: Named +Default value: None +Accept pipeline input: False +Accept wildcard characters: False +``` + +### CommonParameters + +This cmdlet supports the common parameters: -Debug, -ErrorAction, -ErrorVariable, +-InformationAction, -InformationVariable, -OutVariable, -OutBuffer, -PipelineVariable, -Verbose, +-WarningAction, and -WarningVariable. For more information, see +[about_CommonParameters](/powershell/module/microsoft.powershell.core/about/about_commonparameters). + +## INPUTS + +### None + +## OUTPUTS + +### System.String[] + +## NOTES + +## RELATED LINKS + +[Add-ClusterExcludedAdapter](add-clusterexcludedadapter.md) + +[Remove-ClusterExcludedAdapter](remove-clusterexcludedadapter.md) + +[Repair-ClusterNameAccount](repair-clusternameaccount.md) + +[Set-ClusterExcludedAdapter](set-clusterexcludedadapter.md) diff --git a/docset/winserver2025-ps/failoverclusters/New-WorkgroupCluster.md b/docset/winserver2025-ps/failoverclusters/New-WorkgroupCluster.md new file mode 100644 index 0000000000..1c4c0fbd37 --- /dev/null +++ b/docset/winserver2025-ps/failoverclusters/New-WorkgroupCluster.md @@ -0,0 +1,286 @@ +--- +description: Use this topic to help manage Windows and Windows Server technologies with Windows PowerShell. +external help file: Microsoft.FailoverClusters.Adless.PowerShell.psm1-help.xml +Module Name: FailoverClusters +ms.date: 09/11/2024 +online version: https://learn.microsoft.com/powershell/module/failoverclusters/new-workgroupcluster?view=windowsserver2025-ps&wt.mc_id=ps-gethelp +schema: 2.0.0 +title: New-WorkgroupCluster +--- + +# New-WorkgroupCluster + +## SYNOPSIS +Creates a new workgroup cluster. + +## SYNTAX + +``` +New-WorkgroupCluster [[-Node] ] [[-Credentials] ] [[-Name] ] + [[-StaticAddress] ] [[-IgnoreNetwork] ] + [[-ManagementPointNetworkType] ] + [[-AdministrativeAccessPoint] ] [-NoStorage] [-S2D] [-Force] [-Confirm] [-WhatIf] + [] +``` + +## DESCRIPTION + +The `New-WorkgroupCluster` cmdlet creates a new workgroup cluster. + +## EXAMPLES + +### EXAMPLE 1 + +```powershell +New-WorkgroupCluster -Node "Node1", "Node2" -Credentials $cred1, $cred2 -Name "Cluster1" +``` + +This example creates a new workgroup cluster named `Cluster1` with `Node1` and `Node2` using +the credentials in `$cred1` and `$cred2`. + +Note: Only None and DNS are supported for AdministrativeAccessPoint. + +## PARAMETERS + +### -Node + +An array of nodes to be included in the cluster. + +```yaml +Type: String[] +Parameter Sets: (All) +Aliases: + +Required: False +Position: 1 +Default value: @() +Accept pipeline input: False +Accept wildcard characters: False +``` + +### -Credentials + +An array of credentials for the nodes. + +```yaml +Type: PSCredential[] +Parameter Sets: (All) +Aliases: + +Required: False +Position: 2 +Default value: None +Accept pipeline input: False +Accept wildcard characters: False +``` + +### -Name + +The name of the workgroup cluster. + +```yaml +Type: String +Parameter Sets: (All) +Aliases: + +Required: False +Position: 3 +Default value: None +Accept pipeline input: False +Accept wildcard characters: False +``` + +### -StaticAddress + +Specifies one or more static addresses to use when running the cmdlet. Networks with DHCP enabled +are always included, but other networks need a static address to be specified using the +**StaticAddress** parameter or should be explicitly ignored with this **IgnoreNetwork** parameter. + +```yaml +Type: String[] +Parameter Sets: (All) +Aliases: + +Required: False +Position: 4 +Default value: None +Accept pipeline input: False +Accept wildcard characters: False +``` + +### -IgnoreNetwork + +Specifies one or more networks to ignore when running the cmdlet. Networks with DHCP enabled are +always included, but other networks need a static address to be specified using the +**StaticAddress** parameter or should be explicitly ignored with this **IgnoreNetwork** parameter. + +```yaml +Type: String[] +Parameter Sets: (All) +Aliases: + +Required: False +Position: 5 +Default value: None +Accept pipeline input: False +Accept wildcard characters: False +``` + +### -ManagementPointNetworkType + +Specifies the network configuration used to determine IP address settings. Acceptable values are: + +- `Automatic`: Automatically detects the appropriate setting. + - If SQL Server is running in Azure, it uses `Distributed`. + - If SQL Server is running on-premises, it uses `Singleton`. +- `Singleton`: The traditional method of DHCP or static IP address. +- `Distributed`: Uses a Distributed Network Name by using Node IP addresses. + +For on-prem SQL Server, if the value is set to `Automatic`, it defaults to `Singleton`. + +```yaml +Type: AdminAccessPointResType +Parameter Sets: (All) +Aliases: +Accepted values: Automatic, Singleton, Distributed + +Required: False +Position: 6 +Default value: None +Accept pipeline input: False +Accept wildcard characters: False +``` + +### -AdministrativeAccessPoint + +Specifies the type of administrative access point that the cmdlet creates for the cluster. +Acceptable values are: + +- `DNS`: The cmdlet creates an administrative access point for the cluster. The administrative + access point is registered in DNS but isn't enabled in Active Directory Domain Services. +- `None` + +The cmdlet doesn't create an administrative access point for the cluster. Some clustered roles and +functionality might not be available for a cluster that doesn't have an administrative access +point. Also, you cannot use Failover Cluster Manager to manage a cluster that doesn't have an +administrative access point. + +```yaml +Type: AdminAccessPoint +Parameter Sets: (All) +Aliases: +Accepted values: None, Dns + +Required: False +Position: 7 +Default value: None +Accept pipeline input: False +Accept wildcard characters: False +``` + +### -NoStorage + +Specifies that shared storage is ignored for the workgroup cluster node. + +```yaml +Type: SwitchParameter +Parameter Sets: (All) +Aliases: + +Required: False +Position: Named +Default value: False +Accept pipeline input: False +Accept wildcard characters: False +``` + +### -S2D + +Specifies whether to enable Storage Spaces Direct when creating the workgroup cluster. + +```yaml +Type: SwitchParameter +Parameter Sets: (All) +Aliases: + +Required: False +Position: Named +Default value: False +Accept pipeline input: False +Accept wildcard characters: False +``` + +### -Force + +Forces the command to run without asking for user confirmation. + +```yaml +Type: SwitchParameter +Parameter Sets: (All) +Aliases: + +Required: False +Position: Named +Default value: False +Accept pipeline input: False +Accept wildcard characters: False +``` + +### -Confirm + +Prompts you for confirmation before running the cmdlet. + +```yaml +Type: SwitchParameter +Parameter Sets: (All) +Aliases: + +Required: False +Position: Named +Default value: False +Accept pipeline input: False +Accept wildcard characters: False +``` + +### -WhatIf + +Shows what would happen if the cmdlet runs. The cmdlet isn't run. + +```yaml +Type: SwitchParameter +Parameter Sets: (All) +Aliases: + +Required: False +Position: Named +Default value: False +Accept pipeline input: False +Accept wildcard characters: False +``` + +### CommonParameters + +This cmdlet supports the common parameters: -Debug, -ErrorAction, -ErrorVariable, +-InformationAction, -InformationVariable, -OutVariable, -OutBuffer, -PipelineVariable, -Verbose, +-WarningAction, and -WarningVariable. For more information, see +[about_CommonParameters](/powershell/module/microsoft.powershell.core/about/about_commonparameters). + +## INPUTS + +## OUTPUTS + +## NOTES + +## RELATED LINKS + +[Add-WorkgroupClusterNode](add-workgroupclusternode.md) + +[Remove-WorkgroupCluster](remove-workgroupcluster.md) + +[Remove-WorkgroupClusterNode](remove-workgroupclusternode.md) + +[Set-WorkgroupClusterRemotingConfiguration](set-workgroupclusterremotingconfiguration.md) + +[Test-WorkgroupCluster](test-workgroupcluster.md) + +[Test-WorkgroupClusterRemoting](test-workgroupclusterremoting.md) diff --git a/docset/winserver2025-ps/failoverclusters/Remove-ClusterExcludedAdapter.md b/docset/winserver2025-ps/failoverclusters/Remove-ClusterExcludedAdapter.md new file mode 100644 index 0000000000..ac93ba27f4 --- /dev/null +++ b/docset/winserver2025-ps/failoverclusters/Remove-ClusterExcludedAdapter.md @@ -0,0 +1,167 @@ +--- +description: Use this topic to help manage Windows and Windows Server technologies with Windows PowerShell. +external help file: Microsoft.FailoverClusters.PowerShell.dll-Help.xml +Module Name: FailoverClusters +ms.date: 08/28/2024 +online version: https://learn.microsoft.com/powershell/module/failoverclusters/remove-clusterexcludedadapter?view=windowsserver2025-ps&wt.mc_id=ps-gethelp +schema: 2.0.0 +title: Remove-ClusterExcludedAdapter +--- + +# Remove-ClusterExcludedAdapter + +## SYNOPSIS +Removes a network adapter from the list of excluded adapters. + +## SYNTAX + +``` +Remove-ClusterExcludedAdapter -ExclusionType -ExclusionValue + [-CimSession ] [-ThrottleLimit ] [-AsJob] [] +``` + +## DESCRIPTION + +The `Remove-ClusterExcludedAdapter` cmdlet removes a network adapter from a list of network +adapters that should be excluded from use by the Failover Cluster. By default, the cluster will use +all available network adapters, but in some cases you may want to reserve certain adapters as +backup or management, such as Dell iDRAC or HPE iLO. + +## EXAMPLES + +### Example 1 + +```powershell +Remove-ClusterExcludedAdapter -ExclusionType "IPPrefix" -ExclusionValue "10.10.20.25" +``` + +This example removes the network adapter based on the IP Address `10.10.20.25` from the list of +excluded adapters. + +## PARAMETERS + +### -AsJob + +Runs the cmdlet as a background job. Use this parameter to run commands that take a long time to +complete. + +The cmdlet immediately returns an object that represents the job and then displays the command +prompt. You can continue to work in the session while the job completes. + +For more information about Windows PowerShell background jobs, see +[about_Jobs](/powershell/module/microsoft.powershell.core/about/about_jobs). + +```yaml +Type: SwitchParameter +Parameter Sets: (All) +Aliases: + +Required: False +Position: Named +Default value: None +Accept pipeline input: False +Accept wildcard characters: False +``` + +### -CimSession + +Runs the cmdlet in a remote session or on a remote computer. Enter a computer name or a session +object, such as the output of a [New-CimSession](/powershell/module/cimcmdlets/new-cimsession) +or [Get-CimSession](/powershell/module/cimcmdlets/get-cimsession) cmdlet. The default is the +current session on the local computer. + +```yaml +Type: CimSession[] +Parameter Sets: (All) +Aliases: Session + +Required: False +Position: Named +Default value: None +Accept pipeline input: False +Accept wildcard characters: False +``` + +### -ExclusionType + +Specifies the type of exclusion to remove from the cluster. Acceptable values are: + +- `IPPrefix`: Excludes a network adapter based on its IP address. +- `Description`: Excludes a network adapter based on its description. +- `FriendlyName`: Excludes a network adapter based on its friendly name. + +```yaml +Type: AdapterExclusionType +Parameter Sets: (All) +Aliases: +Accepted values: IPPrefix, Description, FriendlyName + +Required: True +Position: Named +Default value: None +Accept pipeline input: False +Accept wildcard characters: False +``` + +### -ExclusionValue + +Specifies the value to use for the exclusion. The value of this parameter depends on the value of +the `-ExclusionType` parameter. + +```yaml +Type: String[] +Parameter Sets: (All) +Aliases: + +Required: True +Position: Named +Default value: None +Accept pipeline input: False +Accept wildcard characters: False +``` + +### -ThrottleLimit + +Specifies the maximum number of concurrent operations that can be established to run the cmdlet. If +this parameter is omitted or a value of `0` is entered, then PowerShell calculates an optimum +throttle limit for the cmdlet based on the number of CIM cmdlets that are running on the computer. +The throttle limit applies only to the current cmdlet, not to the session or to the computer. + +```yaml +Type: Int32 +Parameter Sets: (All) +Aliases: + +Required: False +Position: Named +Default value: None +Accept pipeline input: False +Accept wildcard characters: False +``` + +### CommonParameters + +This cmdlet supports the common parameters: -Debug, -ErrorAction, -ErrorVariable, +-InformationAction, -InformationVariable, -OutVariable, -OutBuffer, -PipelineVariable, -Verbose, +-WarningAction, and -WarningVariable. For more information, see +[about_CommonParameters](/powershell/module/microsoft.powershell.core/about/about_commonparameters). + +## INPUTS + +### None + +## OUTPUTS + +### System.Object + +## NOTES + +## RELATED LINKS + +[Add-ClusterExcludedAdapter](add-clusterexcludedadapter.md) + +[Get-ClusterExcludedAdapter](get-clusterexcludedadapter.md) + +[Repair-ClusterNameAccount](repair-clusternameaccount.md) + +[Set-ClusterExcludedAdapter](set-clusterexcludedadapter.md) diff --git a/docset/winserver2025-ps/failoverclusters/Remove-WorkgroupCluster.md b/docset/winserver2025-ps/failoverclusters/Remove-WorkgroupCluster.md new file mode 100644 index 0000000000..f08fbaf834 --- /dev/null +++ b/docset/winserver2025-ps/failoverclusters/Remove-WorkgroupCluster.md @@ -0,0 +1,147 @@ +--- +description: Use this topic to help manage Windows and Windows Server technologies with Windows PowerShell. +external help file: Microsoft.FailoverClusters.Adless.PowerShell.psm1-help.xml +Module Name: FailoverClusters +ms.date: 09/11/2024 +online version: https://learn.microsoft.com/powershell/module/failoverclusters/remove-workgroupcluster?view=windowsserver2025-ps&wt.mc_id=ps-gethelp +schema: 2.0.0 +title: Remove-WorkgroupCluster +--- + +# Remove-WorkgroupCluster + +## SYNOPSIS +Removes a workgroup cluster. + +## SYNTAX + +``` +Remove-WorkgroupCluster [[-Node] ] [[-Credentials] ] [-Force] [-Confirm] + [-WhatIf] [] +``` + +## DESCRIPTION + +The `Remove-WorkgroupCluster` cmdlet removes a workgroup cluster. + +## EXAMPLES + +### EXAMPLE 1 + +```powershell +Remove-WorkgroupCluster -Node "Node1", "Node2" -Credentials $cred1, $cred2 +``` + +This example removes the cluster from both `Node1` and `Node2`. + +If communication is lost with a node or the membership isn't complete, the cluster might not +be removed and manual cleanup may be needed. + +## PARAMETERS + +### -Node + +An array of nodes that form the current cluster. + +```yaml +Type: String[] +Parameter Sets: (All) +Aliases: + +Required: False +Position: 1 +Default value: @() +Accept pipeline input: False +Accept wildcard characters: False +``` + +### -Credentials + +An array of credentials for the nodes. + +```yaml +Type: PSCredential[] +Parameter Sets: (All) +Aliases: + +Required: False +Position: 2 +Default value: None +Accept pipeline input: False +Accept wildcard characters: False +``` + +### -Force + +Forces the command to run without asking for user confirmation. + +```yaml +Type: SwitchParameter +Parameter Sets: (All) +Aliases: + +Required: False +Position: Named +Default value: False +Accept pipeline input: False +Accept wildcard characters: False +``` + +### -Confirm + +Prompts you for confirmation before running the cmdlet. + +```yaml +Type: SwitchParameter +Parameter Sets: (All) +Aliases: + +Required: False +Position: Named +Default value: False +Accept pipeline input: False +Accept wildcard characters: False +``` + +### -WhatIf + +Shows what would happen if the cmdlet runs. The cmdlet isn't run. + +```yaml +Type: SwitchParameter +Parameter Sets: (All) +Aliases: + +Required: False +Position: Named +Default value: False +Accept pipeline input: False +Accept wildcard characters: False +``` + +### CommonParameters + +This cmdlet supports the common parameters: -Debug, -ErrorAction, -ErrorVariable, +-InformationAction, -InformationVariable, -OutVariable, -OutBuffer, -PipelineVariable, -Verbose, +-WarningAction, and -WarningVariable. For more information, see +[about_CommonParameters](/powershell/module/microsoft.powershell.core/about/about_commonparameters). + +## INPUTS + +## OUTPUTS + +## NOTES + +## RELATED LINKS + +[Add-WorkgroupClusterNode](add-workgroupclusternode.md) + +[New-WorkgroupCluster](new-workgroupcluster.md) + +[Remove-WorkgroupClusterNode](remove-workgroupclusternode.md) + +[Set-WorkgroupClusterRemotingConfiguration](set-workgroupclusterremotingconfiguration.md) + +[Test-WorkgroupCluster](test-workgroupcluster.md) + +[Test-WorkgroupClusterRemoting](test-workgroupclusterremoting.md) diff --git a/docset/winserver2025-ps/failoverclusters/Remove-WorkgroupClusterNode.md b/docset/winserver2025-ps/failoverclusters/Remove-WorkgroupClusterNode.md new file mode 100644 index 0000000000..e3e63f393b --- /dev/null +++ b/docset/winserver2025-ps/failoverclusters/Remove-WorkgroupClusterNode.md @@ -0,0 +1,235 @@ +--- +description: Use this topic to help manage Windows and Windows Server technologies with Windows PowerShell. +external help file: Microsoft.FailoverClusters.Adless.PowerShell.psm1-help.xml +Module Name: FailoverClusters +ms.date: 09/11/2024 +online version: https://learn.microsoft.com/powershell/module/failoverclusters/remove-workgroupclusternode?view=windowsserver2025-ps&wt.mc_id=ps-gethelp +schema: 2.0.0 +title: Remove-WorkgroupClusterNode +--- + +# Remove-WorkgroupClusterNode + +## SYNOPSIS +Removes a node from a workgroup cluster. + +## SYNTAX + +``` +Remove-WorkgroupClusterNode [-Node] [-Credentials] [-Name] + [[-Wait] ] [-IgnoreStorageConnectivityLoss] [-CleanupDisks] [-Force] [-Confirm] [-WhatIf] + [] +``` + +## DESCRIPTION + +The `Remove-WorkgroupCluster` function removes a node from the membership in a workgroup Cluster. +The rest of the parameters will be forwarded to the `Remove-ClusterNode` function. Please refer to +the documentation for the +[Remove-ClusterNode](/powershell/module/failoverclusters/remove-clusternode) cmdlet. + +## EXAMPLES + +### EXAMPLE 1 + +```powershell +Remove-WorkgroupClusterNode -Node "Node1", "Node2" -Credentials $cred1, $cred2 -Name $Node2 +``` + +This example removes `Node2` from the cluster membership. + +### EXAMPLE 2 + +```powershell +Remove-WorkgroupClusterNode -Node "Node1", "Node2" -Credentials $cred1, $cred2 -Name $Node3 +``` + +This example removes `Node3` from the cluster membership. + +Manual cleanup may be required to clear the node state by logging into `Node3` and running +`Clear-ClusterNode`. + +## PARAMETERS + +### -Node + +An array of nodes in the workgroup cluster. + +```yaml +Type: String[] +Parameter Sets: (All) +Aliases: + +Required: True +Position: 1 +Default value: None +Accept pipeline input: False +Accept wildcard characters: False +``` + +### -Credentials + +An array of credentials for the nodes. + +```yaml +Type: PSCredential[] +Parameter Sets: (All) +Aliases: + +Required: True +Position: 2 +Default value: None +Accept pipeline input: False +Accept wildcard characters: False +``` + +### -Name + +The name of the node to be removed. If the name isn't included in **Node** parameter, the first +node in the **Node** parameter will be used to remove the node. Additional cleanup will be required +to clear the node state. + +```yaml +Type: String +Parameter Sets: (All) +Aliases: + +Required: True +Position: 3 +Default value: None +Accept pipeline input: False +Accept wildcard characters: False +``` + +### -Wait + +Specifies the time in seconds to wait for the cmdlet. If the **Wait** parameter isn't specified, +then the cmdlet waits for completion. If the value `0` is specified, then the call is initiated and +the cmdlet returns without waiting. + +```yaml +Type: Int32 +Parameter Sets: (All) +Aliases: + +Required: False +Position: 4 +Default value: 0 +Accept pipeline input: False +Accept wildcard characters: False +``` + +### -CleanupDisks + +Removes any residual cluster metadata from the specified disks. This metadata includes information +that the cluster service uses to manage the disks. By cleaning the metadata, the disks are freed +from any old cluster configurations, making them available for new clusters or other purposes. This +cmdlet may prevent potential conflicts that could arise from leftover metadata when reusing disks. + +```yaml +Type: SwitchParameter +Parameter Sets: (All) +Aliases: + +Required: False +Position: Named +Default value: False +Accept pipeline input: False +Accept wildcard characters: False +``` + +### -Force + +Forces the command to run without asking for user confirmation. + +```yaml +Type: SwitchParameter +Parameter Sets: (All) +Aliases: + +Required: False +Position: Named +Default value: False +Accept pipeline input: False +Accept wildcard characters: False +``` + +### -IgnoreStorageConnectivityLoss + +Indicates that this cmdlet doesn't check whether the cluster node contains non-shared storage, if +Storage Spaces Direct is enabled. If you don't specify this parameter, the cmdlet checks whether +this node has any Storage Spaces Direct storage. If this cmdlet finds Storage Spaces Direct storage, +it prompts you for confirmation before it removes the node. + +```yaml +Type: SwitchParameter +Parameter Sets: (All) +Aliases: + +Required: False +Position: Named +Default value: False +Accept pipeline input: False +Accept wildcard characters: False +``` + +### -Confirm + +Prompts you for confirmation before running the cmdlet. + +```yaml +Type: SwitchParameter +Parameter Sets: (All) +Aliases: + +Required: False +Position: Named +Default value: False +Accept pipeline input: False +Accept wildcard characters: False +``` + +### -WhatIf + +Shows what would happen if the cmdlet runs. The cmdlet isn't run. + +```yaml +Type: SwitchParameter +Parameter Sets: (All) +Aliases: + +Required: False +Position: Named +Default value: False +Accept pipeline input: False +Accept wildcard characters: False +``` + +### CommonParameters + +This cmdlet supports the common parameters: -Debug, -ErrorAction, -ErrorVariable, +-InformationAction, -InformationVariable, -OutVariable, -OutBuffer, -PipelineVariable, -Verbose, +-WarningAction, and -WarningVariable. For more information, see +[about_CommonParameters](/powershell/module/microsoft.powershell.core/about/about_commonparameters). + +## INPUTS + +## OUTPUTS + +## NOTES + +## RELATED LINKS + +[Add-WorkgroupClusterNode](add-workgroupclusternode.md) + +[Clear-ClusterNode](clear-clusternode.md) + +[New-WorkgroupCluster](new-workgroupcluster.md) + +[Remove-WorkgroupCluster](remove-workgroupcluster.md) + +[Set-WorkgroupClusterRemotingConfiguration](set-workgroupclusterremotingconfiguration.md) + +[Test-WorkgroupCluster](test-workgroupcluster.md) + +[Test-WorkgroupClusterRemoting](test-workgroupclusterremoting.md) diff --git a/docset/winserver2025-ps/failoverclusters/Repair-ClusterNameAccount.md b/docset/winserver2025-ps/failoverclusters/Repair-ClusterNameAccount.md new file mode 100644 index 0000000000..00e5a2d80b --- /dev/null +++ b/docset/winserver2025-ps/failoverclusters/Repair-ClusterNameAccount.md @@ -0,0 +1,156 @@ +--- +description: Use this topic to help manage Windows and Windows Server technologies with Windows PowerShell. +external help file: Microsoft.FailoverClusters.PowerShell.dll-Help.xml +Module Name: FailoverClusters +ms.date: 08/28/2024 +online version: https://learn.microsoft.com/powershell/module/failoverclusters/repair-clusternameaccount?view=windowsserver2025-ps&wt.mc_id=ps-gethelp +schema: 2.0.0 +title: Repair-ClusterNameAccount +--- + +# Repair-ClusterNameAccount + +## SYNOPSIS +Repairs the Cluster Name Account and ensures that the cluster continues to function properly. + +## SYNTAX + +### InputObject (Default) + +``` +Repair-ClusterNameAccount [-Credentials ] [-Domain ] [-InputObject ] + [-Cluster ] [] +``` + +### Credentials + +``` +Repair-ClusterNameAccount [-Credentials ] [-Domain ] [-Cluster ] + [] +``` + +## DESCRIPTION + +The `Repair-ClusterNameAccount` cmdlet repairs or updates the Cluster Name Account used for +authentication and authorization on a Failover Cluster. The Cluster Name Account is used to create +Highly Available applications or Virtual Computer Objects (VCOs) in the cluster. + +To learn more about cluster accounts in domain environments, see +[Configuring cluster accounts in Active Directory](/windows-server/failover-clustering/configure-ad-accounts). + +## EXAMPLES + +### Example 1 + +```powershell +Repair-ClusterNameAccount -Cluster "Cluster01" +``` + +This example repairs or updates the Cluster Name Account for the cluster named `Cluster01`. + +### Example 2 + +```powershell +$cred = Get-Credential +Repair-ClusterNameAccount -Cluster "Cluster01" -Credentials $cred -Domain "contoso.com" +``` + +This example repairs or updates the Cluster Name Account for the cluster named `Cluster01` using +the specified credentials and domain. The `Get-Credential` cmdlet is used to create a PSCredential +object for the `-Credentials` parameter. + +## PARAMETERS + +### -Cluster + +Specifies the name of the cluster on which to run this cmdlet. If the input for this parameter is +`.` or it is omitted, then the cmdlet runs on the local cluster. + +```yaml +Type: String +Parameter Sets: (All) +Aliases: + +Required: False +Position: Named +Default value: None +Accept pipeline input: False +Accept wildcard characters: False +``` + +### -Credentials + +Specifies the credentials that this cmdlet uses when it connects to Active Directory Domain +Services. + +```yaml +Type: PSCredential +Parameter Sets: (All) +Aliases: + +Required: False +Position: Named +Default value: None +Accept pipeline input: False +Accept wildcard characters: False +``` + +### -Domain + +Specifies the name of the domain in which to repair the cluster name account. This should be the +fully qualified domain name (FQDN) of the domain that the cluster is in. + +```yaml +Type: String +Parameter Sets: (All) +Aliases: + +Required: False +Position: Named +Default value: None +Accept pipeline input: False +Accept wildcard characters: False +``` + +### -InputObject + +Specifies the cluster name account to repair. + +```yaml +Type: PSObject +Parameter Sets: InputObject +Aliases: + +Required: False +Position: Named +Default value: None +Accept pipeline input: True (ByValue) +Accept wildcard characters: False +``` + +### CommonParameters + +This cmdlet supports the common parameters: -Debug, -ErrorAction, -ErrorVariable, +-InformationAction, -InformationVariable, -OutVariable, -OutBuffer, -PipelineVariable, -Verbose, +-WarningAction, and -WarningVariable. For more information, see +[about_CommonParameters](/powershell/module/microsoft.powershell.core/about/about_commonparameters). + +## INPUTS + +### System.Management.Automation.PSObject + +## OUTPUTS + +### System.Object + +## NOTES + +## RELATED LINKS + +[Add-ClusterExcludedAdapter](add-clusterexcludedadapter.md) + +[Get-ClusterExcludedAdapter](get-clusterexcludedadapter.md) + +[Remove-ClusterExcludedAdapter](remove-clusterexcludedadapter.md) + +[Set-ClusterExcludedAdapter](set-clusterexcludedadapter.md) diff --git a/docset/winserver2025-ps/failoverclusters/Set-ClusterExcludedAdapter.md b/docset/winserver2025-ps/failoverclusters/Set-ClusterExcludedAdapter.md new file mode 100644 index 0000000000..354b7bd1d5 --- /dev/null +++ b/docset/winserver2025-ps/failoverclusters/Set-ClusterExcludedAdapter.md @@ -0,0 +1,168 @@ +--- +description: Use this topic to help manage Windows and Windows Server technologies with Windows PowerShell. +external help file: Microsoft.FailoverClusters.PowerShell.dll-Help.xml +Module Name: FailoverClusters +ms.date: 08/28/2024 +online version: https://learn.microsoft.com/powershell/module/failoverclusters/set-clusterexcludedadapter?view=windowsserver2025-ps&wt.mc_id=ps-gethelp +schema: 2.0.0 +title: Set-ClusterExcludedAdapter +--- + +# Set-ClusterExcludedAdapter + +## SYNOPSIS +Sets a network adapter to the list of excluded adapters. + +## SYNTAX + +``` +Set-ClusterExcludedAdapter -ExclusionType -ExclusionValue + [-CimSession ] [-ThrottleLimit ] [-AsJob] [] +``` + +## DESCRIPTION + +The `Set-ClusterExcludedAdapter` cmdlet configures a network adapter in a list of network adapters +that should be excluded from use by the Failover Cluster. By default, the cluster will use all +available network adapters, but in some cases you may want to reserve certain adapters as backup or +management, such as Dell iDRAC or HPE iLO. + +## EXAMPLES + +### Example 1 + +```powershell +Set-ClusterExcludedAdapter -ExclusionType "Description" -ExclusionValue "Node-1-FL1","Node-1-FL2" +``` + +This example sets the list of excluded network adapters for the cluster. After running this +command, the cluster will no longer use `Node-1-FL1` or `Node-1-FL2` for cluster communications, +ensuring that they are available for management or backup purposes. + +## PARAMETERS + +### -AsJob + +Runs the cmdlet as a background job. Use this parameter to run commands that take a long time to +complete. + +The cmdlet immediately returns an object that represents the job and then displays the command +prompt. You can continue to work in the session while the job completes. + +For more information about Windows PowerShell background jobs, see +[about_Jobs](/powershell/module/microsoft.powershell.core/about/about_jobs). + +```yaml +Type: SwitchParameter +Parameter Sets: (All) +Aliases: + +Required: False +Position: Named +Default value: None +Accept pipeline input: False +Accept wildcard characters: False +``` + +### -CimSession + +Runs the cmdlet in a remote session or on a remote computer. Enter a computer name or a session +object, such as the output of a [New-CimSession](/powershell/module/cimcmdlets/new-cimsession) +or [Get-CimSession](/powershell/module/cimcmdlets/get-cimsession) cmdlet. The default is the +current session on the local computer. + +```yaml +Type: CimSession[] +Parameter Sets: (All) +Aliases: Session + +Required: False +Position: Named +Default value: None +Accept pipeline input: False +Accept wildcard characters: False +``` + +### -ExclusionType + +Specifies the type of exclusion to remove from the cluster. Acceptable values are: + +- `IPPrefix`: Excludes a network adapter based on its IP address. +- `Description`: Excludes a network adapter based on its description. +- `FriendlyName`: Excludes a network adapter based on its friendly name. + +```yaml +Type: AdapterExclusionType +Parameter Sets: (All) +Aliases: +Accepted values: IPPrefix, Description, FriendlyName + +Required: True +Position: Named +Default value: None +Accept pipeline input: False +Accept wildcard characters: False +``` + +### -ExclusionValue + +Specifies the value to use for the exclusion. The value of this parameter depends on the value of +the `-ExclusionType` parameter. + +```yaml +Type: String[] +Parameter Sets: (All) +Aliases: + +Required: True +Position: Named +Default value: None +Accept pipeline input: False +Accept wildcard characters: False +``` + +### -ThrottleLimit + +Specifies the maximum number of concurrent operations that can be established to run the cmdlet. If +this parameter is omitted or a value of `0` is entered, then PowerShell calculates an optimum +throttle limit for the cmdlet based on the number of CIM cmdlets that are running on the computer. +The throttle limit applies only to the current cmdlet, not to the session or to the computer. + +```yaml +Type: Int32 +Parameter Sets: (All) +Aliases: + +Required: False +Position: Named +Default value: None +Accept pipeline input: False +Accept wildcard characters: False +``` + +### CommonParameters + +This cmdlet supports the common parameters: -Debug, -ErrorAction, -ErrorVariable, +-InformationAction, -InformationVariable, -OutVariable, -OutBuffer, -PipelineVariable, -Verbose, +-WarningAction, and -WarningVariable. For more information, see +[about_CommonParameters](/powershell/module/microsoft.powershell.core/about/about_commonparameters). + +## INPUTS + +### None + +## OUTPUTS + +### System.Object + +## NOTES + +## RELATED LINKS + +[Add-ClusterExcludedAdapter](add-clusterexcludedadapter.md) + +[Get-ClusterExcludedAdapter](get-clusterexcludedadapter.md) + +[Remove-ClusterExcludedAdapter](remove-clusterexcludedadapter.md) + +[Repair-ClusterNameAccount](repair-clusternameaccount.md) diff --git a/docset/winserver2025-ps/failoverclusters/Set-WorkgroupClusterRemotingConfiguration.md b/docset/winserver2025-ps/failoverclusters/Set-WorkgroupClusterRemotingConfiguration.md new file mode 100644 index 0000000000..99b29e07f6 --- /dev/null +++ b/docset/winserver2025-ps/failoverclusters/Set-WorkgroupClusterRemotingConfiguration.md @@ -0,0 +1,69 @@ +--- +description: Use this topic to help manage Windows and Windows Server technologies with Windows PowerShell. +external help file: Microsoft.FailoverClusters.Adless.PowerShell.psm1-help.xml +Module Name: FailoverClusters +ms.date: 09/11/2024 +online version: https://learn.microsoft.com/powershell/module/failoverclusters/set-workgroupclusterremotingconfiguration?view=windowsserver2025-ps&wt.mc_id=ps-gethelp +schema: 2.0.0 +title: Set-WorkgroupClusterRemotingConfiguration +--- + +# Set-WorkgroupClusterRemotingConfiguration + +## SYNOPSIS +Configures the remote management settings for a failover cluster that is part of a workgroup. + +## SYNTAX + +``` +Set-WorkgroupClusterRemotingConfiguration [] +``` + +## DESCRIPTION + +The `Set-WorkgroupClusterRemotingConfiguration` cmdlet configures the remote management settings for +a failover cluster that is part of a workgroup. + +## EXAMPLES + +### Example 1 + +```powershell +Set-WorkgroupClusterRemotingConfiguration -Verbose +``` + +This example displays detailed information about the current workgroup cluster remoting +configuration. + +## PARAMETERS + +### CommonParameters + +This cmdlet supports the common parameters: -Debug, -ErrorAction, -ErrorVariable, +-InformationAction, -InformationVariable, -OutVariable, -OutBuffer, -PipelineVariable, -Verbose, +-WarningAction, and -WarningVariable. For more information, see +[about_CommonParameters](/powershell/module/microsoft.powershell.core/about/about_commonparameters). + +## INPUTS + +### None + +## OUTPUTS + +### System.Object + +## NOTES + +## RELATED LINKS + +[Add-WorkgroupClusterNode](add-workgroupclusternode.md) + +[New-WorkgroupCluster](new-workgroupcluster.md) + +[Remove-WorkgroupCluster](remove-workgroupcluster.md) + +[Remove-WorkgroupClusterNode](remove-workgroupclusternode.md) + +[Test-WorkgroupCluster](test-workgroupcluster.md) + +[Test-WorkgroupClusterRemoting](test-workgroupclusterremoting.md) diff --git a/docset/winserver2025-ps/failoverclusters/Test-WorkgroupCluster.md b/docset/winserver2025-ps/failoverclusters/Test-WorkgroupCluster.md new file mode 100644 index 0000000000..0d68dd5b64 --- /dev/null +++ b/docset/winserver2025-ps/failoverclusters/Test-WorkgroupCluster.md @@ -0,0 +1,294 @@ +--- +description: Use this topic to help manage Windows and Windows Server technologies with Windows PowerShell. +external help file: Microsoft.FailoverClusters.Adless.PowerShell.psm1-help.xml +Module Name: FailoverClusters +ms.date: 09/11/2024 +online version: https://learn.microsoft.com/powershell/module/failoverclusters/test-workgroupcluster?view=windowsserver2025-ps&wt.mc_id=ps-gethelp +schema: 2.0.0 +title: Test-WorkgroupCluster +--- + +# Test-WorkgroupCluster + +## SYNOPSIS +Tests the configuration of a workgroup cluster. + +## SYNTAX + +``` +Test-WorkgroupCluster [[-Node] ] [[-Credentials] ] [[-Disk] ] + [[-Pool] ] [[-ReportName] ] [[-Include] ] [[-Ignore] ] + [-Force] [[-Cluster] ] [-Confirm] [-WhatIf] [-Destination] [] +``` + +## DESCRIPTION + +The `Test-WorkgroupCluster` function tests the configuration of a workgroup cluster. The rest of +the parameters will be forwarded to the `Test-Cluster` function. Please refer to the documentation +for the [Test-Cluster](/powershell/module/failoverclusters/test-cluster) cmdlet. + +## EXAMPLES + +### EXAMPLE 1 + +```powershell +Test-WorkgroupCluster -Node "Node1", "Node2" -Credentials $cred1, $cred2 +``` + +This example tests the configuration of a workgroup cluster with `Node1` and `Node2` using the +credentials in `$cred1` and `$cred2`, and additional parameters. + +## PARAMETERS + +### -Node + +An array of nodes in the workgroup cluster. + +```yaml +Type: String[] +Parameter Sets: (All) +Aliases: + +Required: False +Position: 2 +Default value: @() +Accept pipeline input: False +Accept wildcard characters: False +``` + +### -Credentials + +An array of credentials for the nodes. + +```yaml +Type: PSCredential[] +Parameter Sets: (All) +Aliases: + +Required: False +Position: 3 +Default value: None +Accept pipeline input: False +Accept wildcard characters: False +``` + +### -Disk + +Specifies the disk number or disks for which to run the cmdlet. If the specified disk is online and +is assigned to a clustered role or Cluster Shared Volume, you must also specify the **Force** +parameter to take the disk offline for the duration of the storage tests. Otherwise, the specified +disk must be offline before the cmdlet is run. + +If the **Disk** parameter isn't specified, storage tests run on all disks that are available for +use in the cluster or that are in the cluster resource offline or failed state. + +Acceptable values are: + +- **Int32, Int64, Uint32, or Uint64**: A number that represents a master boot record (MBR) + signature of the disk. +- **System.String**: A string that represents a master boot record (MBR) signature of the disk, + hexadecimal format is supported, or a string that represents the GUID of a GPT disk. +- **ClusterResource**: A cluster resource object that represents a clustered disk. +- **CimInstance#MSFT_Disk**: An object returned from `Get-Disk`, from the Windows PowerShell storage + module. + +```yaml +Type: Object[] +Parameter Sets: (All) +Aliases: + +Required: False +Position: 4 +Default value: None +Accept pipeline input: False +Accept wildcard characters: False +``` + +### -Pool + +Specifies the clustered storage pool or pools for which to run the cmdlet. When the specified +storage pool is online and a virtual disk in the storage pool is assigned to a clustered role or +Cluster Shared Volume, you must also specify the **Force** parameter to take the storage pool +offline for the duration of the storage tests. Otherwise, the command will exit with an error. + +The specified storage pool must be taken offline before running the storage tests. If the **Pool** +parameter isn't specified, storage tests run on all storage pools that are available for use in the +cluster or that are in the cluster resource offline or failed state. + +Acceptable values are: + +- **System.String**: A string that represents the name of the clustered storage pool or pools. +- **ClusterResource**: A cluster resource object that represents a clustered storage pool. +- **CimInstance#MSFT_StoragePool**: An object returned from `Get-StoragePool`, from the Windows + PowerShell storage module. + +```yaml +Type: Object[] +Parameter Sets: (All) +Aliases: + +Required: False +Position: 5 +Default value: None +Accept pipeline input: False +Accept wildcard characters: False +``` + +### -ReportName + +Specifies the name of the test report to generate. + +```yaml +Type: String +Parameter Sets: (All) +Aliases: + +Required: False +Position: 6 +Default value: None +Accept pipeline input: False +Accept wildcard characters: False +``` + +### -Include + +Specifies which tests or category of tests to include during the validation test run. Only the tests +or category of tests specified will run. + +```yaml +Type: String[] +Parameter Sets: (All) +Aliases: + +Required: False +Position: 7 +Default value: None +Accept pipeline input: False +Accept wildcard characters: False +``` + +### -Ignore + +Specifies which tests or category of tests to ignore during the validation test run. All other +tests or category of tests will run. + +```yaml +Type: String[] +Parameter Sets: (All) +Aliases: + +Required: False +Position: 8 +Default value: None +Accept pipeline input: False +Accept wildcard characters: False +``` + +### -Force + +Forces the command to run without asking for user confirmation. + +```yaml +Type: SwitchParameter +Parameter Sets: (All) +Aliases: + +Required: False +Position: 9 +Default value: False +Accept pipeline input: False +Accept wildcard characters: False +``` + +### -Cluster + +Specifies the name of the cluster on which to run this cmdlet. If the input for this parameter is +`.` or it is omitted, then the cmdlet runs on the local cluster. + +```yaml +Type: String +Parameter Sets: (All) +Aliases: + +Required: False +Position: 10 +Default value: None +Accept pipeline input: False +Accept wildcard characters: False +``` + +### -Confirm + +Prompts you for confirmation before running the cmdlet. + +```yaml +Type: SwitchParameter +Parameter Sets: (All) +Aliases: + +Required: False +Position: 11 +Default value: False +Accept pipeline input: False +Accept wildcard characters: False +``` + +### -WhatIf + +Shows what would happen if the cmdlet runs. The cmdlet isn't run. + +```yaml +Type: SwitchParameter +Parameter Sets: (All) +Aliases: + +Required: False +Position: 12 +Default value: False +Accept pipeline input: False +Accept wildcard characters: False +``` + +### -Destination + +Specifies the location to which to copy one or more cluster logs. To copy to the current folder, use +`.` for this parameter input. Default location is `C:\Windows\Cluster\Reports`. + +```yaml +Type: String +Parameter Sets: (All) +Aliases: + +Required: True +Position: 13 +Default value: (Get-Location).Path +Accept pipeline input: False +Accept wildcard characters: False +``` + +### CommonParameters + +This cmdlet supports the common parameters: -Debug, -ErrorAction, -ErrorVariable, +-InformationAction, -InformationVariable, -OutVariable, -OutBuffer, -PipelineVariable, -Verbose, +-WarningAction, and -WarningVariable. For more information, see +[about_CommonParameters](/powershell/module/microsoft.powershell.core/about/about_commonparameters). + +## INPUTS + +## OUTPUTS + +## NOTES + +## RELATED LINKS + +[Add-WorkgroupClusterNode](add-workgroupclusternode.md) + +[New-WorkgroupCluster](new-workgroupcluster.md) + +[Remove-WorkgroupCluster](remove-workgroupcluster.md) + +[Remove-WorkgroupClusterNode](remove-workgroupclusternode.md) + +[Set-WorkgroupClusterRemotingConfiguration](set-workgroupclusterremotingconfiguration.md) + +[Test-WorkgroupClusterRemoting](test-workgroupclusterremoting.md) diff --git a/docset/winserver2025-ps/failoverclusters/Test-WorkgroupClusterRemoting.md b/docset/winserver2025-ps/failoverclusters/Test-WorkgroupClusterRemoting.md new file mode 100644 index 0000000000..25a1a2be22 --- /dev/null +++ b/docset/winserver2025-ps/failoverclusters/Test-WorkgroupClusterRemoting.md @@ -0,0 +1,98 @@ +--- +description: Use this topic to help manage Windows and Windows Server technologies with Windows PowerShell. +external help file: Microsoft.FailoverClusters.Adless.PowerShell.psm1-help.xml +Module Name: FailoverClusters +ms.date: 09/11/2024 +online version: https://learn.microsoft.com/powershell/module/failoverclusters/test-workgroupclusterremoting?view=windowsserver2025-ps&wt.mc_id=ps-gethelp +schema: 2.0.0 +title: Test-WorkgroupClusterRemoting +--- + +# Test-WorkgroupClusterRemoting + +## SYNOPSIS +Tests if remoting is configured on all nodes. + +## SYNTAX + +``` +Test-WorkgroupClusterRemoting [[-Node] ] [[-Credentials] ] + [] +``` + +## DESCRIPTION + +The `Test-WorkgroupClusterRemoting` function tests if remoting is configured on all nodes. It also +verifies if CredSSP is configured. + +## EXAMPLES + +### EXAMPLE 1 + +```powershell +Test-WorkgroupClusterRemoting -Node "Node1", "Node2" -Credentials $cred1, $cred2 +``` + +This example tests if remoting is configured on `Node1` and `Node2` using the credentials in +`$cred1` and `$cred2`. + +## PARAMETERS + +### -Node + +An array of nodes to test remoting on. + +```yaml +Type: String[] +Parameter Sets: (All) +Aliases: + +Required: False +Position: 2 +Default value: @() +Accept pipeline input: False +Accept wildcard characters: False +``` + +### -Credentials + +An array of credentials for the nodes. + +```yaml +Type: PSCredential[] +Parameter Sets: (All) +Aliases: + +Required: False +Position: 3 +Default value: None +Accept pipeline input: False +Accept wildcard characters: False +``` + +### CommonParameters + +This cmdlet supports the common parameters: -Debug, -ErrorAction, -ErrorVariable, +-InformationAction, -InformationVariable, -OutVariable, -OutBuffer, -PipelineVariable, -Verbose, +-WarningAction, and -WarningVariable. For more information, see +[about_CommonParameters](/powershell/module/microsoft.powershell.core/about/about_commonparameters). + +## INPUTS + +## OUTPUTS + +## NOTES + +## RELATED LINKS + +[Add-WorkgroupClusterNode](add-workgroupclusternode.md) + +[New-WorkgroupCluster](new-workgroupcluster.md) + +[Remove-WorkgroupCluster](remove-workgroupcluster.md) + +[Remove-WorkgroupClusterNode](remove-workgroupclusternode.md) + +[Set-WorkgroupClusterRemotingConfiguration](set-workgroupclusterremotingconfiguration.md) + +[Test-WorkgroupCluster](test-workgroupcluster.md) diff --git a/docset/winserver2025-ps/hyper-v/Add-VMAssignableDevice.md b/docset/winserver2025-ps/hyper-v/Add-VMAssignableDevice.md new file mode 100644 index 0000000000..8524d0f863 --- /dev/null +++ b/docset/winserver2025-ps/hyper-v/Add-VMAssignableDevice.md @@ -0,0 +1,275 @@ +--- +description: Assigns a device to a virtual machine. +external help file: Microsoft.HyperV.PowerShell.Cmdlets.dll-Help.xml +Module Name: Hyper-V +ms.date: 06/12/2024 +online version: https://learn.microsoft.com/powershell/module/hyper-v/add-vmassignabledevice?view=windowsserver2025-ps&wt.mc_id=ps-gethelp +schema: 2.0.0 +title: Add-VMAssignableDevice +--- + +# Add-VMAssignableDevice + +## SYNOPSIS +Adds an assignable device to a specific virtual machine. + +## SYNTAX + +### VMName (Default) + +``` +Add-VMAssignableDevice [-CimSession ] [-ComputerName ] + [-Credential ] [-VMName] [-InstancePath ] + [-LocationPath ] [-VirtualFunction ] [-ResourcePoolName ] [-Passthru] + [-WhatIf] [-Confirm] [] +``` + +### VMObject + +``` +Add-VMAssignableDevice [-VM] [-InstancePath ] [-LocationPath ] + [-VirtualFunction ] [-ResourcePoolName ] [-Passthru] [-WhatIf] [-Confirm] + [] +``` + +## DESCRIPTION + +The `Add-VMAssignableDevice` cmdlet assigns a physical device to a specified virtual machine (VM). +This is commonly used for tasks such as attaching GPUs or network adapters directly to a VM to +enhance performance for specific applications or workloads. The device can be specified through its +instance path, location path, or assignable device object. + +## EXAMPLES + +### Example 1 + +```powershell +Add-VMAssignableDevice -VMName "MyVM" -InstancePath "PCIROOT(0)#PCI(0300)#PCI(0000)" +``` + +This example attaches a physical device, identified by its instance path, to the virtual machine +named **MyVM**. + +## PARAMETERS + +### -CimSession + +Runs the cmdlet in a remote session or on a remote computer. Enter a computer name or a session +object, such as the output of a [New-CimSession](/powershell/module/cimcmdlets/new-cimsession) +or [Get-CimSession](/powershell/module/cimcmdlets/get-cimsession) cmdlet. The default is the +current session on the local computer. + +```yaml +Type: CimSession[] +Parameter Sets: VMName +Aliases: + +Required: False +Position: Named +Default value: None +Accept pipeline input: False +Accept wildcard characters: False +``` + +### -ComputerName + +Specifies one or more Hyper-V hosts on which the assignable devices are to be retrieved. NetBIOS +names, IP addresses, and fully qualified domain names are allowed. The default is the local +computer. Use localhost or a dot (`.`) to specify the local computer explicitly. + +```yaml +Type: String[] +Parameter Sets: VMName +Aliases: + +Required: False +Position: Named +Default value: None +Accept pipeline input: False +Accept wildcard characters: False +``` + +### -Credential + +Specifies one or more user accounts that have permission to perform this action. The default is the +current user. + +```yaml +Type: PSCredential[] +Parameter Sets: VMName +Aliases: + +Required: False +Position: Named +Default value: None +Accept pipeline input: False +Accept wildcard characters: False +``` + +### -InstancePath + +Represents the Device Instance path in the host machine. + +```yaml +Type: String +Parameter Sets: (All) +Aliases: + +Required: False +Position: Named +Default value: None +Accept pipeline input: False +Accept wildcard characters: False +``` + +### -LocationPath + +Specifies the location path to the assignable device + +```yaml +Type: String +Parameter Sets: (All) +Aliases: + +Required: False +Position: Named +Default value: None +Accept pipeline input: False +Accept wildcard characters: False +``` + +### -Passthru + +Returns an object for each process that the cmdlet started. + +```yaml +Type: SwitchParameter +Parameter Sets: (All) +Aliases: + +Required: False +Position: Named +Default value: None +Accept pipeline input: False +Accept wildcard characters: False +``` + +### -ResourcePoolName + +Specifies the name of the resource pool to which the device is to be assigned. + +```yaml +Type: String +Parameter Sets: (All) +Aliases: + +Required: False +Position: Named +Default value: None +Accept pipeline input: False +Accept wildcard characters: False +``` + +### -VirtualFunction + +Specifies the number of the virtual function (VF) of an SR-IOV-capable network adapter assigned to +the virtual machine. + +```yaml +Type: UInt16 +Parameter Sets: (All) +Aliases: + +Required: False +Position: Named +Default value: None +Accept pipeline input: False +Accept wildcard characters: False +``` + +### -VM + +Specifies the virtual machine to which the device is to be assigned. + +```yaml +Type: VirtualMachine[] +Parameter Sets: VMObject +Aliases: + +Required: True +Position: 0 +Default value: None +Accept pipeline input: True (ByValue) +Accept wildcard characters: False +``` + +### -VMName + +Specifies the name of the virtual machine to which the device is to be assigned. + +```yaml +Type: String[] +Parameter Sets: VMName +Aliases: + +Required: True +Position: 0 +Default value: None +Accept pipeline input: False +Accept wildcard characters: False +``` + +### -Confirm + +Prompts you for confirmation before running the cmdlet. + +```yaml +Type: SwitchParameter +Parameter Sets: (All) +Aliases: cf + +Required: False +Position: Named +Default value: None +Accept pipeline input: False +Accept wildcard characters: False +``` + +### -WhatIf + +Shows what would happen if the cmdlet runs. The cmdlet is not run. + +```yaml +Type: SwitchParameter +Parameter Sets: (All) +Aliases: wi + +Required: False +Position: Named +Default value: None +Accept pipeline input: False +Accept wildcard characters: False +``` + +### CommonParameters + +This cmdlet supports the common parameters: -Debug, -ErrorAction, -ErrorVariable, +-InformationAction, -InformationVariable, -OutVariable, -OutBuffer, -PipelineVariable, -Verbose, +-WarningAction, and -WarningVariable. For more information, see +[about_CommonParameters](/powershell/module/microsoft.powershell.core/about/about_commonparameters). + +## INPUTS + +### Microsoft.HyperV.PowerShell.VirtualMachine[] + +## OUTPUTS + +### Microsoft.HyperV.PowerShell.VMAssignedDevice + +## NOTES + +## RELATED LINKS + +[Get-VMAssignableDevice](get-vmassignabledevice.md) + +[Remove-VMAssignableDevice](remove-vmassignabledevice.md) diff --git a/docset/winserver2025-ps/hyper-v/Add-VMGpuPartitionAdapter.md b/docset/winserver2025-ps/hyper-v/Add-VMGpuPartitionAdapter.md index c20efc5557..df04c023ca 100644 --- a/docset/winserver2025-ps/hyper-v/Add-VMGpuPartitionAdapter.md +++ b/docset/winserver2025-ps/hyper-v/Add-VMGpuPartitionAdapter.md @@ -2,7 +2,7 @@ description: Adds a GPU partition adapter to a virtual machine. external help file: Microsoft.HyperV.PowerShell.Cmdlets.dll-Help.xml Module Name: Hyper-V -ms.date: 09/22/2022 +ms.date: 06/12/2024 online version: https://learn.microsoft.com/powershell/module/hyper-v/add-vmgpupartitionadapter?view=windowsserver2025-ps&wt.mc_id=ps-gethelp schema: 2.0.0 title: Add-VMGpuPartitionAdapter @@ -16,53 +16,62 @@ Adds a GPU partition adapter to a virtual machine. ## SYNTAX ### VMName (Default) + ``` Add-VMGpuPartitionAdapter [-CimSession ] [-ComputerName ] [-Credential ] [-VMName] [-Passthru] [-InstancePath ] [-MinPartitionVRAM ] [-MaxPartitionVRAM ] [-OptimalPartitionVRAM ] [-MinPartitionEncode ] [-MaxPartitionEncode ] [-OptimalPartitionEncode ] [-MinPartitionDecode ] [-MaxPartitionDecode ] [-OptimalPartitionDecode ] - [-MinPartitionCompute ] [-MaxPartitionCompute ] [-OptimalPartitionCompute ] [-WhatIf] - [-Confirm] [] + [-MinPartitionCompute ] [-MaxPartitionCompute ] [-OptimalPartitionCompute ] + [-WhatIf] [-Confirm] [] ``` ### VMObject + ``` Add-VMGpuPartitionAdapter [-VM] [-Passthru] [-InstancePath ] [-MinPartitionVRAM ] [-MaxPartitionVRAM ] [-OptimalPartitionVRAM ] [-MinPartitionEncode ] [-MaxPartitionEncode ] [-OptimalPartitionEncode ] [-MinPartitionDecode ] [-MaxPartitionDecode ] [-OptimalPartitionDecode ] - [-MinPartitionCompute ] [-MaxPartitionCompute ] [-OptimalPartitionCompute ] [-WhatIf] - [-Confirm] [] + [-MinPartitionCompute ] [-MaxPartitionCompute ] [-OptimalPartitionCompute ] + [-WhatIf] [-Confirm] [] ``` ## DESCRIPTION -The 'Add-VMGpuPartitionAdapter' cmdlet adds a GPU partition adapter to a virtual machine. With no parameter, it assigns a full partition from an assignable GPU to a VM. + +The `Add-VMGpuPartitionAdapter` cmdlet adds a GPU partition adapter to a virtual machine. With no +parameter, it assigns a full partition from an assignable GPU to a VM. ## EXAMPLES ### Example 1 + ```powershell -$vm = Get-VM -name "TestVM" +$vm = Get-VM -Name "TestVM" Add-VMGpuPartitionAdapter -VM $vm ``` This example assigns a partition to a specific VM object. ### Example 2 + ```powershell -$vm = Get-VM -name "TestVM" -Add-VMGpuPartitionAdapter -VM $vm -Instancepath "SampleGPUInstancePath" +$vm = Get-VM -Name "TestVM" +Add-VMGpuPartitionAdapter -VM $vm -InstancePath "GPUInstancePath" ``` -This example assigns a partition from a specific GPU to a VM where the instance path is the GPU device ID name on the host. +This example assigns a partition from a specific GPU to a VM where the instance path is the GPU +device ID name on the host. ## PARAMETERS ### -CimSession -Runs the cmdlet in a remote session or on a remote computer. -Enter a computer name or a session object, such as the output of a [New-CimSession](https://go.microsoft.com/fwlink/p/?LinkId=227967) or [Get-CimSession](https://go.microsoft.com/fwlink/p/?LinkId=227966) cmdlet. -The default is the current session on the local computer. + +Runs the cmdlet in a remote session or on a remote computer. Enter a computer name or a session +object, such as the output of a [New-CimSession](/powershell/module/cimcmdlets/new-cimsession) +or [Get-CimSession](/powershell/module/cimcmdlets/get-cimsession) cmdlet. The default is the +current session on the local computer. ```yaml Type: CimSession[] @@ -77,10 +86,10 @@ Accept wildcard characters: False ``` ### -ComputerName -Specifies one or more Hyper-V hosts from which virtual machines are to be retrieved. -NetBIOS names, IP addresses, and fully qualified domain names are allowable. -The default is the local computer. -Use localhost or a dot ('.') to specify the local computer explicitly. + +Specifies one or more Hyper-V hosts from which virtual machines are to be retrieved. NetBIOS names, +IP addresses, and fully qualified domain names are allowable. The default is the local computer. +Use localhost or a dot (`.`) to specify the local computer explicitly. ```yaml Type: String[] @@ -95,8 +104,9 @@ Accept wildcard characters: False ``` ### -Credential -Specifies one or more user accounts that have permission to perform this action. -The default is the current user. + +Specifies one or more user accounts that have permission to perform this action. The default is the +current user. ```yaml Type: PSCredential[] @@ -111,7 +121,9 @@ Accept wildcard characters: False ``` ### -InstancePath -Represents the Device Instance path of a GPU in the host. This value can be obtained from the "Name" property of the command 'Get-VMHostPartitionableGpu'. + +Represents the Device Instance path of a GPU in the host. This value can be obtained from the +"Name" property of the command `Get-VMHostPartitionableGpu`. ```yaml Type: String @@ -126,7 +138,9 @@ Accept wildcard characters: False ``` ### -MaxPartitionCompute -The maximum number of compute assigned by the host GPU. This is defined by the manufacturer's driver. + +The maximum number of compute assigned by the host GPU. This is defined by the manufacturer's +driver. ```yaml Type: UInt64 @@ -141,7 +155,9 @@ Accept wildcard characters: False ``` ### -MaxPartitionDecode -The maximum number of decoders assigned by the host GPU. This is defined by the manufacturer's driver. + +The maximum number of decoders assigned by the host GPU. This is defined by the manufacturer's +driver. ```yaml Type: UInt64 @@ -156,7 +172,9 @@ Accept wildcard characters: False ``` ### -MaxPartitionEncode -The maximum number of encoders assigned by the host GPU. This is defined by the manufacturer's driver. + +The maximum number of encoders assigned by the host GPU. This is defined by the manufacturer's +driver. ```yaml Type: UInt64 @@ -171,6 +189,7 @@ Accept wildcard characters: False ``` ### -MaxPartitionVRAM + The maximum VRAM in bytes supported by the host GPU. This is defined by the manufacturer's driver. ```yaml @@ -186,7 +205,9 @@ Accept wildcard characters: False ``` ### -MinPartitionCompute -The minimum number of compute assigned by the host GPU. This is defined by the manufacturer's driver. + +The minimum number of compute assigned by the host GPU. This is defined by the manufacturer's +driver. ```yaml Type: UInt64 @@ -201,7 +222,9 @@ Accept wildcard characters: False ``` ### -MinPartitionDecode -The minimum number of decoders assigned by the host GPU. This is defined by the manufacturer's driver. + +The minimum number of decoders assigned by the host GPU. This is defined by the manufacturer's +driver. ```yaml Type: UInt64 @@ -216,7 +239,9 @@ Accept wildcard characters: False ``` ### -MinPartitionEncode -The minimum number of encoders assigned by the host GPU. This is defined by the manufacturer's driver. + +The minimum number of encoders assigned by the host GPU. This is defined by the manufacturer's +driver. ```yaml Type: UInt64 @@ -231,6 +256,7 @@ Accept wildcard characters: False ``` ### -MinPartitionVRAM + The minimum VRAM in bytes supported by the host GPU. This is defined by the manufacturer's driver. ```yaml @@ -246,7 +272,9 @@ Accept wildcard characters: False ``` ### -OptimalPartitionCompute -The optimal number of compute assigned by the host GPU. This is defined by the manufacturer's driver. + +The optimal number of compute assigned by the host GPU. This is defined by the manufacturer's +driver. ```yaml Type: UInt64 @@ -261,7 +289,9 @@ Accept wildcard characters: False ``` ### -OptimalPartitionDecode -The optimal number of decoders assigned by the host GPU. This is defined by the manufacturer's driver. + +The optimal number of decoders assigned by the host GPU. This is defined by the manufacturer's +driver. ```yaml Type: UInt64 @@ -276,7 +306,9 @@ Accept wildcard characters: False ``` ### -OptimalPartitionEncode -The optimal number of encoders assigned by the host GPU. This is defined by the manufacturer's driver. + +The optimal number of encoders assigned by the host GPU. This is defined by the manufacturer's +driver. ```yaml Type: UInt64 @@ -291,6 +323,7 @@ Accept wildcard characters: False ``` ### -OptimalPartitionVRAM + The optimal VRAM in bytes supported by the host GPU. This is defined by the manufacturer's driver. ```yaml @@ -306,6 +339,7 @@ Accept wildcard characters: False ``` ### -Passthru + Returns an object for each process that the cmdlet started. ```yaml @@ -321,6 +355,7 @@ Accept wildcard characters: False ``` ### -VM + Specifies the virtual machine on which the network adapter is to be added. ```yaml @@ -336,6 +371,7 @@ Accept wildcard characters: False ``` ### -VMName + Specifies the name of the virtual machine on which the network adapter is to be added. ```yaml @@ -351,6 +387,7 @@ Accept wildcard characters: False ``` ### -Confirm + Prompts you for confirmation before running the cmdlet. ```yaml @@ -366,8 +403,8 @@ Accept wildcard characters: False ``` ### -WhatIf -Shows what would happen if the cmdlet runs. -The cmdlet is not run. + +Shows what would happen if the cmdlet runs. The cmdlet is not run. ```yaml Type: SwitchParameter @@ -382,7 +419,11 @@ Accept wildcard characters: False ``` ### CommonParameters -This cmdlet supports the common parameters: -Debug, -ErrorAction, -ErrorVariable, -InformationAction, -InformationVariable, -OutVariable, -OutBuffer, -PipelineVariable, -Verbose, -WarningAction, and -WarningVariable. For more information, see [about_CommonParameters](https://go.microsoft.com/fwlink/?LinkID=113216). + +This cmdlet supports the common parameters: -Debug, -ErrorAction, -ErrorVariable, +-InformationAction, -InformationVariable, -OutVariable, -OutBuffer, -PipelineVariable, -Verbose, +-WarningAction, and -WarningVariable. For more information, see +[about_CommonParameters](/powershell/module/microsoft.powershell.core/about/about_commonparameters). ## INPUTS @@ -397,3 +438,9 @@ This cmdlet supports the common parameters: -Debug, -ErrorAction, -ErrorVariable ## NOTES ## RELATED LINKS + +[Get-VMGpuPartitionAdapter](get-vmgpupartitionadapter.md) + +[Remove-VMGpuPartitionAdapter](remove-vmgpupartitionadapter.md) + +[Set-VMGpuPartitionAdapter](set-vmgpupartitionadapter.md) diff --git a/docset/winserver2025-ps/hyper-v/Add-VMHostAssignableDevice.md b/docset/winserver2025-ps/hyper-v/Add-VMHostAssignableDevice.md new file mode 100644 index 0000000000..faa9a5dff8 --- /dev/null +++ b/docset/winserver2025-ps/hyper-v/Add-VMHostAssignableDevice.md @@ -0,0 +1,227 @@ +--- +description: Assigns a device to a virtual machine host. +external help file: Microsoft.HyperV.PowerShell.Cmdlets.dll-Help.xml +Module Name: Hyper-V +ms.date: 06/12/2024 +online version: https://learn.microsoft.com/powershell/module/hyper-v/add-vmhostassignabledevice?view=windowsserver2025-ps&wt.mc_id=ps-gethelp +schema: 2.0.0 +title: Add-VMHostAssignableDevice +--- + +# Add-VMHostAssignableDevice + +## SYNOPSIS +Adds an assignable device to a virtual machine (VM) host. + +## SYNTAX + +### Path (Default) + +``` +Add-VMHostAssignableDevice [-CimSession ] [-ComputerName ] + [-Credential ] [-Force] [-InstancePath ] [-LocationPath ] + -ResourcePoolName [] +``` + +### Object + +``` +Add-VMHostAssignableDevice [-Force] [-HostAssignableDevice] + -ResourcePoolName [] +``` + +## DESCRIPTION + +The `Add-VMHostAssignableDevice` cmdlet assigns a hardware device to a virtual machine host. You +can add devices to the VM host by providing either the instance or location path of the device, or +by specifying an existing host-assignable device object. + +## EXAMPLES + +### Example 1 + +```powershell +$params = @{ +ComputerName = "MyVM01" +InstancePath = "PCI\VEN_8086&DEV_0F48&SUBSYS_72708086&REV_0B\3&11583659&0&D8" +ResourcePoolName = "MyResourcePool" +} +Add-VMHostAssignableDevice $params +``` + +This example assigns a device identified by its instance path to VM host **MyVM01** within the +resource pool **MyResourcePool**. + +### Example 2 + +```powershell +$gpu = Get-VMHostAssignableDevice +Add-VMHostAssignableDevice -HostAssignableDevice $gpu -ResourcePoolName "GpuChildPool" +``` + +This example retrieves a list of GPUs or other assignable devices and adds these devices to a +resource pool named **GpuChildPool**, making the devices available for use by virtual machines in +that resource pool. + +## PARAMETERS + +### -CimSession + +Runs the cmdlet in a remote session or on a remote computer. Enter a computer name or a session +object, such as the output of a [New-CimSession](/powershell/module/cimcmdlets/new-cimsession) +or [Get-CimSession](/powershell/module/cimcmdlets/get-cimsession) cmdlet. The default is the +current session on the local computer. + +```yaml +Type: CimSession[] +Parameter Sets: Path +Aliases: + +Required: False +Position: Named +Default value: None +Accept pipeline input: False +Accept wildcard characters: False +``` + +### -ComputerName + +Specifies the name of the Hyper-V host to which the device is to be added. NetBIOS names, IP +addresses, and fully qualified domain names are allowed. The default is the local computer. Use +localhost or a dot (`.`) to specify the local computer explicitly. + +```yaml +Type: String[] +Parameter Sets: Path +Aliases: + +Required: False +Position: Named +Default value: None +Accept pipeline input: False +Accept wildcard characters: False +``` + +### -Credential + +Specifies one or more user accounts that have permission to perform this action. The default is the +current user. + +```yaml +Type: PSCredential[] +Parameter Sets: Path +Aliases: + +Required: False +Position: Named +Default value: None +Accept pipeline input: False +Accept wildcard characters: False +``` + +### -Force + +Forces the command to run without asking for user confirmation. + +```yaml +Type: SwitchParameter +Parameter Sets: (All) +Aliases: + +Required: False +Position: Named +Default value: None +Accept pipeline input: False +Accept wildcard characters: False +``` + +### -HostAssignableDevice + +Specifies the device object to be assigned to the virtual machine. + +```yaml +Type: VMHostAssignableDevice[] +Parameter Sets: Object +Aliases: VMHostAssignableDevice + +Required: True +Position: 0 +Default value: None +Accept pipeline input: True (ByValue) +Accept wildcard characters: False +``` + +### -InstancePath + +Represents the Device Instance path in the host machine. + +```yaml +Type: String +Parameter Sets: Path +Aliases: + +Required: False +Position: Named +Default value: None +Accept pipeline input: False +Accept wildcard characters: False +``` + +### -LocationPath + +Specifies the location path to the assignable device. + +```yaml +Type: String +Parameter Sets: Path +Aliases: + +Required: False +Position: Named +Default value: None +Accept pipeline input: False +Accept wildcard characters: False +``` + +### -ResourcePoolName + +Specifies the name of the resource pool to which the device is assigned. + +```yaml +Type: String[] +Parameter Sets: (All) +Aliases: + +Required: True +Position: Named +Default value: None +Accept pipeline input: False +Accept wildcard characters: False +``` + +### CommonParameters + +This cmdlet supports the common parameters: -Debug, -ErrorAction, -ErrorVariable, +-InformationAction, -InformationVariable, -OutVariable, -OutBuffer, -PipelineVariable, -Verbose, +-WarningAction, and -WarningVariable. For more information, see +[about_CommonParameters](/powershell/module/microsoft.powershell.core/about/about_commonparameters). + +## INPUTS + +### Microsoft.HyperV.PowerShell.VMHostAssignableDevice[] + +## OUTPUTS + +### System.Object + +## NOTES + +## RELATED LINKS + +[Get-VMHostAssignableDevice](get-vmhostassignabledevice.md) + +[Dismount-VMHostAssignableDevice](dismount-vmhostassignabledevice.md) + +[Mount-VMHostAssignableDevice](mount-vmhostassignabledevice.md) + +[Remove-VMHostAssignableDevice](remove-vmhostassignabledevice.md) diff --git a/docset/winserver2025-ps/hyper-v/Dismount-VMHostAssignableDevice.md b/docset/winserver2025-ps/hyper-v/Dismount-VMHostAssignableDevice.md new file mode 100644 index 0000000000..7cd62ac1e9 --- /dev/null +++ b/docset/winserver2025-ps/hyper-v/Dismount-VMHostAssignableDevice.md @@ -0,0 +1,225 @@ +--- +description: Dismounts an assignable device from a virtual machine host. +external help file: Microsoft.HyperV.PowerShell.Cmdlets.dll-Help.xml +Module Name: Hyper-V +ms.date: 06/12/2024 +online version: https://learn.microsoft.com/powershell/module/hyper-v/dismount-vmhostassignabledevice?view=windowsserver2025-ps&wt.mc_id=ps-gethelp +schema: 2.0.0 +title: Dismount-VMHostAssignableDevice +--- + +# Dismount-VMHostAssignableDevice + +## SYNOPSIS +Dismounts a device from a virtual machine (VM) host. + +## SYNTAX + +``` +Dismount-VMHostAssignableDevice [-InstancePath ] [-LocationPath ] [-Force] + [-Passthru] [-CimSession ] [-ComputerName ] [-Credential ] + [-WhatIf] [-Confirm] [] +``` + +## DESCRIPTION + +The `Dismount-VMHostAssignableDevice` cmdlet is used to dismount an assignable device from the +virtual machine host. Use this cmdlet when you need to reassign a device or resolve conflicts +between devices and virtual machines. + +## EXAMPLES + +### Example 1 + +```powershell +Dismount-VMHostAssignableDevice -InstancePath "PCIROOT(0)#PCI(1D02)#PCI(0000)" +``` + +This example dismounts the device with the specified instance path from the host, making it +available for assignment to a virtual machine. + +## PARAMETERS + +### -CimSession + +Runs the cmdlet in a remote session or on a remote computer. Enter a computer name or a session +object, such as the output of a [New-CimSession](/powershell/module/cimcmdlets/new-cimsession) +or [Get-CimSession](/powershell/module/cimcmdlets/get-cimsession) cmdlet. The default is the +current session on the local computer. + +```yaml +Type: CimSession[] +Parameter Sets: (All) +Aliases: + +Required: False +Position: Named +Default value: None +Accept pipeline input: False +Accept wildcard characters: False +``` + +### -ComputerName + +Specifies one or more Hyper-V hosts from which the assignable devices are to be dismounted. NetBIOS +names, IP addresses, and fully qualified domain names are allowed. The default is the local +computer. Use localhost or a dot (`.`) to specify the local computer explicitly. + +```yaml +Type: String[] +Parameter Sets: Path +Aliases: + +Required: False +Position: Named +Default value: None +Accept pipeline input: False +Accept wildcard characters: False +``` + +### -Credential + +Specifies one or more user accounts that have permission to perform this action. The default is the +current user. + +```yaml +Type: PSCredential[] +Parameter Sets: (All) +Aliases: + +Required: False +Position: Named +Default value: None +Accept pipeline input: False +Accept wildcard characters: False +``` + +### -Force + +Forces the command to run without asking for user confirmation. + +Using the **Force** parameter also overrides some security checks in the platform. To learn more, +see [Dismount the device from the host partition +](/windows-server/virtualization/hyper-v/deploy/deploying-graphics-devices-using-dda#dismount-the-device-from-the-host-partition). + +If no partitioning driver is provided, during dismount, you must use `-Force` to bypass the +security warning. For more information about the security implications, see [Plan for deploying devices by using Discrete Device Assignment](/windows-server/virtualization/hyper-v/plan/plan-for-deploying-devices-using-discrete-device-assignment). + +```yaml +Type: SwitchParameter +Parameter Sets: (All) +Aliases: + +Required: False +Position: Named +Default value: None +Accept pipeline input: False +Accept wildcard characters: False +``` + +### -InstancePath + +Represents the Device Instance path in the host machine. + +```yaml +Type: String +Parameter Sets: (All) +Aliases: + +Required: False +Position: Named +Default value: None +Accept pipeline input: False +Accept wildcard characters: False +``` + +### -LocationPath + +Specifies the location path to the assignable device. + +```yaml +Type: String +Parameter Sets: (All) +Aliases: + +Required: False +Position: Named +Default value: None +Accept pipeline input: False +Accept wildcard characters: False +``` + +### -Passthru + +Returns an object for each process that the cmdlet started. + +```yaml +Type: SwitchParameter +Parameter Sets: (All) +Aliases: + +Required: False +Position: Named +Default value: None +Accept pipeline input: False +Accept wildcard characters: False +``` + +### -Confirm + +Prompts you for confirmation before running the cmdlet. + +```yaml +Type: SwitchParameter +Parameter Sets: (All) +Aliases: cf + +Required: False +Position: Named +Default value: None +Accept pipeline input: False +Accept wildcard characters: False +``` + +### -WhatIf + +Shows what would happen if the cmdlet runs. The cmdlet is not run. + +```yaml +Type: SwitchParameter +Parameter Sets: (All) +Aliases: wi + +Required: False +Position: Named +Default value: None +Accept pipeline input: False +Accept wildcard characters: False +``` + +### CommonParameters + +This cmdlet supports the common parameters: -Debug, -ErrorAction, -ErrorVariable, +-InformationAction, -InformationVariable, -OutVariable, -OutBuffer, -PipelineVariable, -Verbose, +-WarningAction, and -WarningVariable. For more information, see +[about_CommonParameters](/powershell/module/microsoft.powershell.core/about/about_commonparameters). + +## INPUTS + +### None + +## OUTPUTS + +### Microsoft.HyperV.PowerShell.VMHostAssignableDevice + +## NOTES + +## RELATED LINKS + +[Add-VMHostAssignableDevice](add-vmhostassignabledevice.md) + +[Get-VMHostAssignableDevice](get-vmhostassignabledevice.md) + +[Mount-VMHostAssignableDevice](mount-vmhostassignabledevice.md) + +[Remove-VMHostAssignableDevice](remove-vmhostassignabledevice.md) diff --git a/docset/winserver2025-ps/hyper-v/Get-VMAssignableDevice.md b/docset/winserver2025-ps/hyper-v/Get-VMAssignableDevice.md new file mode 100644 index 0000000000..66fb3601d4 --- /dev/null +++ b/docset/winserver2025-ps/hyper-v/Get-VMAssignableDevice.md @@ -0,0 +1,194 @@ +--- +description: Retrieves information about a device assigned to a virtual machine. +external help file: Microsoft.HyperV.PowerShell.Cmdlets.dll-Help.xml +Module Name: Hyper-V +ms.date: 06/12/2024 +online version: https://learn.microsoft.com/powershell/module/hyper-v/get-vmassignabledevice?view=windowsserver2025-ps&wt.mc_id=ps-gethelp +schema: 2.0.0 +title: Get-VMAssignableDevice +--- + +# Get-VMAssignableDevice + +## SYNOPSIS +Retrieves information about the assignable device from a specific virtual machine. + +## SYNTAX + +### VMName (Default) + +``` +Get-VMAssignableDevice [-CimSession ] [-ComputerName ] + [-Credential ] [-VMName] [-InstancePath ] + [-LocationPath ] [] +``` + +### VMObject + +``` +Get-VMAssignableDevice [-VM] [-InstancePath ] [-LocationPath ] + [] +``` + +## DESCRIPTION + +The `Get-VMAssignableDevice` cmdlet retrieves information about the assignable devices that are +associated with a specific virtual machine (VM). This cmdlet can be used to list all assignable +devices that can be attached to a VM or to retrieve details about specific devices that are already +assigned. The retrieved information can include the device's instance path, location path, and +other relevant properties. + +## EXAMPLES + +### Example 1 + +```powershell +Get-VMAssignableDevice -VMName "MyVM" +``` + +This example retrieves all assignable devices associated with the virtual machine named **MyVM**. + +## PARAMETERS + +### -CimSession + +Runs the cmdlet in a remote session or on a remote computer. Enter a computer name or a session +object, such as the output of a [New-CimSession](/powershell/module/cimcmdlets/new-cimsession) +or [Get-CimSession](/powershell/module/cimcmdlets/get-cimsession) cmdlet. The default is the +current session on the local computer. + +```yaml +Type: CimSession[] +Parameter Sets: VMName +Aliases: + +Required: False +Position: Named +Default value: None +Accept pipeline input: False +Accept wildcard characters: False +``` + +### -ComputerName + +Specifies one or more Hyper-V hosts from which the assignable devices are to be retrieved. NetBIOS +names, IP addresses, and fully qualified domain names are allowed. The default is the local +computer. Use localhost or a dot (`.`) to specify the local computer explicitly. + +```yaml +Type: String[] +Parameter Sets: VMName +Aliases: + +Required: False +Position: Named +Default value: None +Accept pipeline input: False +Accept wildcard characters: False +``` + +### -Credential + +Retrieves one or more user accounts that have permission to perform this action. The default is the +current user. + +```yaml +Type: PSCredential[] +Parameter Sets: VMName +Aliases: + +Required: False +Position: Named +Default value: None +Accept pipeline input: False +Accept wildcard characters: False +``` + +### -InstancePath + +Represents the Device Instance path in the host machine. + +```yaml +Type: String +Parameter Sets: (All) +Aliases: + +Required: False +Position: Named +Default value: None +Accept pipeline input: False +Accept wildcard characters: False +``` + +### -LocationPath + +Specifies the location path to the assignable device + +```yaml +Type: String +Parameter Sets: (All) +Aliases: + +Required: False +Position: Named +Default value: None +Accept pipeline input: False +Accept wildcard characters: False +``` + +### -VM + +Retrieves the virtual machine which a device is assigned. + +```yaml +Type: VirtualMachine[] +Parameter Sets: VMObject +Aliases: + +Required: True +Position: 0 +Default value: None +Accept pipeline input: True (ByValue) +Accept wildcard characters: False +``` + +### -VMName + +Retrieves the names of the assignable devices assigned to the specified virtual machine. + +```yaml +Type: String[] +Parameter Sets: VMName +Aliases: + +Required: True +Position: 0 +Default value: None +Accept pipeline input: True (ByValue) +Accept wildcard characters: False +``` + +### CommonParameters + +This cmdlet supports the common parameters: -Debug, -ErrorAction, -ErrorVariable, +-InformationAction, -InformationVariable, -OutVariable, -OutBuffer, -PipelineVariable, -Verbose, +-WarningAction, and -WarningVariable. For more information, see +[about_CommonParameters](/powershell/module/microsoft.powershell.core/about/about_commonparameters). + +## INPUTS + +### System.String[] + +### Microsoft.HyperV.PowerShell.VirtualMachine[] + +## OUTPUTS + +### Microsoft.HyperV.PowerShell.VMAssignedDevice + +## NOTES + +## RELATED LINKS + +[Add-VMAssignableDevice](add-vmassignabledevice.md) + +[Remove-VMAssignableDevice](remove-vmassignabledevice.md) diff --git a/docset/winserver2025-ps/hyper-v/Get-VMGpuPartitionAdapter.md b/docset/winserver2025-ps/hyper-v/Get-VMGpuPartitionAdapter.md index 4143c49ecd..324563bc61 100644 --- a/docset/winserver2025-ps/hyper-v/Get-VMGpuPartitionAdapter.md +++ b/docset/winserver2025-ps/hyper-v/Get-VMGpuPartitionAdapter.md @@ -2,7 +2,7 @@ description: Gets the information of assigned GPU partitions to a virtual machine. external help file: Microsoft.HyperV.PowerShell.Cmdlets.dll-Help.xml Module Name: Hyper-V -ms.date: 09/22/2022 +ms.date: 06/12/2024 online version: https://learn.microsoft.com/powershell/module/hyper-v/get-vmgpupartitionadapter?view=windowsserver2025-ps&wt.mc_id=ps-gethelp schema: 2.0.0 title: Get-VMGpuPartitionAdapter @@ -16,33 +16,54 @@ Gets the information of assigned GPU partitions to a virtual machine. ## SYNTAX ### VMName (Default) + ``` Get-VMGpuPartitionAdapter [-CimSession ] [-ComputerName ] [-Credential ] [-VMName] [-AdapterId ] [] ``` ### VMObject + ``` Get-VMGpuPartitionAdapter [-VM] [-AdapterId ] [] ``` ## DESCRIPTION -The 'Get-VMGpuPartitionAdapter' cmdlet gets the information of assigned graphic processing unit partitions to a virtual machine. + +The `Get-VMGpuPartitionAdapter` cmdlet gets the information of assigned graphic processing unit +partitions to a virtual machine. ## EXAMPLES ### Example 1 + ```powershell -$testvm = get-VM "TestVM" +$testvm = Get-VM "TestVM" Get-VMGpuPartitionAdapter -VM $testvm ``` This example gets the GPU information assigned to a VM object. +### Example 2 + +```powershell +Get-VMGpuPartitionAdapter -VMName "TestVM" | FL InstancePath, Id, SupportsOutgoingLiveMigration +``` + +This command retrieves information about the GPU partition adapter for the virtual machine named +**TestVM** and displays the `InstancePath`, `Id`, and `SupportsOutgoingLiveMigration` properties. + +When live migrating a virtual machine with a GPU partition adapter, certain hardware and software +conditions must be met on both the source and target hosts. The `SupportsOutgoingLiveMigration` +field can be used to pre-validate a live migration, ensuring that all necessary conditions are met +before attempting the migration. + ## PARAMETERS ### -AdapterId -This is a VM's GPU partition identification number used to display the GPU information assigned to a VM. + +This is a VM's GPU partition identification number used to display the GPU information assigned to a +VM. ```yaml Type: String @@ -57,9 +78,11 @@ Accept wildcard characters: False ``` ### -CimSession -Runs the cmdlet in a remote session or on a remote computer. -Enter a computer name or a session object, such as the output of a [New-CimSession](https://go.microsoft.com/fwlink/p/?LinkId=227967) or [Get-CimSession](https://go.microsoft.com/fwlink/p/?LinkId=227966) cmdlet. -The default is the current session on the local computer. + +Runs the cmdlet in a remote session or on a remote computer. Enter a computer name or a session +object, such as the output of a [New-CimSession](/powershell/module/cimcmdlets/new-cimsession) +or [Get-CimSession](/powershell/module/cimcmdlets/get-cimsession) cmdlet. The default is the +current session on the local computer. ```yaml Type: CimSession[] @@ -74,10 +97,10 @@ Accept wildcard characters: False ``` ### -ComputerName -Specifies one or more Hyper-V hosts on the virtual network adapters are to be retrieved. -NetBIOS names, IP addresses, and fully qualified domain names are allowed. -The default is the local computer. -Use localhost or a dot ('.') to specify the local computer explicitly. + +Specifies one or more Hyper-V hosts on the virtual network adapters are to be retrieved. NetBIOS +names, IP addresses, and fully qualified domain names are allowed. The default is the local +computer. Use localhost or a dot (`.`) to specify the local computer explicitly. ```yaml Type: String[] @@ -92,8 +115,9 @@ Accept wildcard characters: False ``` ### -Credential -Specifies one or more user accounts that have permission to perform this action. -The default is the current user. + +Specifies one or more user accounts that have permission to perform this action. The default is the +current user. ```yaml Type: PSCredential[] @@ -108,6 +132,7 @@ Accept wildcard characters: False ``` ### -VM + Specifies the virtual machine whose virtual network adapters are to be retrieved. The asterisk (`*`) is the wildcard. If it is specified the cmdlet returns virtual network adapters from every virtual machine in the system. @@ -125,6 +150,7 @@ Accept wildcard characters: True ``` ### -VMName + Specifies the name of the virtual machine whose network adapters are to be retrieved. ```yaml @@ -140,7 +166,11 @@ Accept wildcard characters: False ``` ### CommonParameters -This cmdlet supports the common parameters: -Debug, -ErrorAction, -ErrorVariable, -InformationAction, -InformationVariable, -OutVariable, -OutBuffer, -PipelineVariable, -Verbose, -WarningAction, and -WarningVariable. For more information, see [about_CommonParameters](https://go.microsoft.com/fwlink/?LinkID=113216). + +This cmdlet supports the common parameters: -Debug, -ErrorAction, -ErrorVariable, +-InformationAction, -InformationVariable, -OutVariable, -OutBuffer, -PipelineVariable, -Verbose, +-WarningAction, and -WarningVariable. For more information, see +[about_CommonParameters](/powershell/module/microsoft.powershell.core/about/about_commonparameters). ## INPUTS @@ -155,3 +185,9 @@ This cmdlet supports the common parameters: -Debug, -ErrorAction, -ErrorVariable ## NOTES ## RELATED LINKS + +[Add-VMGpuPartitionAdapter](add-vmgpupartitionadapter.md) + +[Remove-VMGpuPartitionAdapter](remove-vmgpupartitionadapter.md) + +[Set-VMGpuPartitionAdapter](set-vmgpupartitionadapter.md) diff --git a/docset/winserver2025-ps/hyper-v/Get-VMHostAssignableDevice.md b/docset/winserver2025-ps/hyper-v/Get-VMHostAssignableDevice.md new file mode 100644 index 0000000000..cd83f1711c --- /dev/null +++ b/docset/winserver2025-ps/hyper-v/Get-VMHostAssignableDevice.md @@ -0,0 +1,178 @@ +--- +description: Retrieves information about an assignable device to a virtual machine host. +external help file: Microsoft.HyperV.PowerShell.Cmdlets.dll-Help.xml +Module Name: Hyper-V +ms.date: 06/12/2024 +online version: https://learn.microsoft.com/powershell/module/hyper-v/get-vmhostassignabledevice?view=windowsserver2025-ps&wt.mc_id=ps-gethelp +schema: 2.0.0 +title: Get-VMHostAssignableDevice +--- + +# Get-VMHostAssignableDevice + +## SYNOPSIS +Retrieves device information assigned to a virtual machine (VM) host. + +## SYNTAX + +``` +Get-VMHostAssignableDevice [-InstancePath ] [-LocationPath ] + [-ResourcePoolName ] [-CimSession ] [-ComputerName ] + [-Credential ] [] +``` + +## DESCRIPTION + +The `Get-VMHostAssignableDevice` cmdlet retrieves information about devices that can be assigned to +a virtual machine host. This can include devices such as GPUs, network adapters, or storage +controllers that are physically present on the host system. The cmdlet can filter devices by their +instance path or location path. + +## EXAMPLES + +### Example 1 + +```powershell +Get-VMHostAssignableDevice +``` + +This example retrieves all assignable devices on the host computer. + +### Example 2 + +```powershell +Get-VMHostAssignableDevice -ComputerName "MyHost" +``` + +In this example, the cmdlet retrieves all assignable devices from the computer named **MyHost**. + +## PARAMETERS + +### -CimSession + +Runs the cmdlet in a remote session or on a remote computer. Enter a computer name or a session +object, such as the output of a [New-CimSession](/powershell/module/cimcmdlets/new-cimsession) +or [Get-CimSession](/powershell/module/cimcmdlets/get-cimsession) cmdlet. The default is the +current session on the local computer. + +```yaml +Type: CimSession[] +Parameter Sets: (All) +Aliases: + +Required: False +Position: Named +Default value: None +Accept pipeline input: False +Accept wildcard characters: False +``` + +### -ComputerName + +Specifies one or more Hyper-V hosts from which the assignable devices are to be retrieved. NetBIOS +names, IP addresses, and fully qualified domain names are allowed. The default is the local +computer. Use localhost or a dot (`.`) to specify the local computer explicitly. + +```yaml +Type: String[] +Parameter Sets: (All) +Aliases: + +Required: False +Position: Named +Default value: None +Accept pipeline input: False +Accept wildcard characters: False +``` + +### -Credential + +Specifies one or more user accounts that have permission to perform this action. The default is the +current user. + +```yaml +Type: PSCredential[] +Parameter Sets: (All) +Aliases: + +Required: False +Position: Named +Default value: None +Accept pipeline input: False +Accept wildcard characters: False +``` + +### -InstancePath + +Represents the Device Instance path in the host machine. + +```yaml +Type: String +Parameter Sets: (All) +Aliases: + +Required: False +Position: Named +Default value: None +Accept pipeline input: False +Accept wildcard characters: False +``` + +### -LocationPath + +Specifies the location path to the assignable device. + +```yaml +Type: String +Parameter Sets: (All) +Aliases: + +Required: False +Position: Named +Default value: None +Accept pipeline input: False +Accept wildcard characters: False +``` + +### -ResourcePoolName + +Retrieves the name of the resource pool to which the device is assigned. + +```yaml +Type: String[] +Parameter Sets: (All) +Aliases: + +Required: False +Position: Named +Default value: None +Accept pipeline input: False +Accept wildcard characters: False +``` + +### CommonParameters + +This cmdlet supports the common parameters: -Debug, -ErrorAction, -ErrorVariable, +-InformationAction, -InformationVariable, -OutVariable, -OutBuffer, -PipelineVariable, -Verbose, +-WarningAction, and -WarningVariable. For more information, see +[about_CommonParameters](/powershell/module/microsoft.powershell.core/about/about_commonparameters). + +## INPUTS + +### None + +## OUTPUTS + +### Microsoft.HyperV.PowerShell.VMHostAssignableDevice + +## NOTES + +## RELATED LINKS + +[Add-VMHostAssignableDevice](add-vmhostassignabledevice.md) + +[Dismount-VMHostAssignableDevice](dismount-vmhostassignabledevice.md) + +[Mount-VMHostAssignableDevice](mount-vmhostassignabledevice.md) + +[Remove-VMHostAssignableDevice](remove-vmhostassignabledevice.md) diff --git a/docset/winserver2025-ps/hyper-v/Get-VMHostPartitionableGpu.md b/docset/winserver2025-ps/hyper-v/Get-VMHostPartitionableGpu.md index 18d7eeec17..9bca7e0ffc 100644 --- a/docset/winserver2025-ps/hyper-v/Get-VMHostPartitionableGpu.md +++ b/docset/winserver2025-ps/hyper-v/Get-VMHostPartitionableGpu.md @@ -2,7 +2,7 @@ description: Gets the host machine’s partitionable GPU. external help file: Microsoft.HyperV.PowerShell.Cmdlets.dll-Help.xml Module Name: Hyper-V -ms.date: 09/22/2022 +ms.date: 06/12/2024 online version: https://learn.microsoft.com/powershell/module/hyper-v/get-vmhostpartitionablegpu?view=windowsserver2025-ps&wt.mc_id=ps-gethelp schema: 2.0.0 title: Get-VMHostPartitionableGpu @@ -16,49 +16,66 @@ Gets the host machine’s partitionable GPU. ## SYNTAX ### ComputerName (Default) + ``` -Get-VMHostPartitionableGpu [[-ComputerName] ] [[-Credential] ] [-Name ] - [] +Get-VMHostPartitionableGpu [[-ComputerName] ] [[-Credential] ] + [-Name ] [] ``` ### CimSession + ``` Get-VMHostPartitionableGpu [-CimSession] [-Name ] [] ``` ## DESCRIPTION -The 'Get-VMHostPartitionableGpu' cmdlet gets the host machine’s partitionable graphic processing unit. -This displays the information of the GPU as provided by the manufacturer's driver. + +The `Get-VMHostPartitionableGpu` cmdlet gets the host machine’s partitionable graphic processing +unit. This displays the information of the GPU as provided by the manufacturer's driver. ## EXAMPLES ### Example 1 -``` + +```powershell Get-VMHostPartitionableGpu ``` This example gets the details of the local partitionable graphic processing unit on the host. ### Example 2 + ```powershell -Get-VMHostPartitionableGpu -ComputerName "SampleHost" +Get-VMHostPartitionableGpu -ComputerName "MyHost" ``` -This example gets a partitionable GPU by using the host name. This command will display all the GPU devices available for partitioning in the host. +This example gets a partitionable GPU by using the host name. This command will display all the GPU +devices available for partitioning in the host. ### Example 3 + +```powershell +Get-VMHostPartitionableGpu -Name "GPUDeviceIDName" +``` + +### Example 4 + ```powershell -Get-VMHostPartitionableGpu -name "SampleGPUDeviceIDName" +Get-VMHostPartitionableGpu | FL Name, ValidPartitionCounts ``` -Displays a partitionable GPU by using the specific GPU device name. The result will show the details of the specific GPU listed. +This example retrieves information about the partitionable GPUs available on a virtual machine host +and formats the output as a list, displaying the name of each GPU and the number of valid +partitions that can be created on each GPU. ## PARAMETERS ### -CimSession -Runs the cmdlet in a remote session or on a remote computer. -Enter a computer name or a session object, such as the output of a [New-CimSession](https://go.microsoft.com/fwlink/p/?LinkId=227967) or [Get-CimSession](https://go.microsoft.com/fwlink/p/?LinkId=227966) cmdlet. -The default is the current session on the local computer. + +Runs the cmdlet in a remote session or on a remote computer. Enter a computer name or a session +object, such as the output of a [New-CimSession](/powershell/module/cimcmdlets/new-cimsession) +or [Get-CimSession](/powershell/module/cimcmdlets/get-cimsession) cmdlet. The default is the +current session on the local computer. ```yaml Type: CimSession[] @@ -73,10 +90,10 @@ Accept wildcard characters: False ``` ### -ComputerName -Specifies one or more Hyper-V hosts that run this cmdlet. -NetBIOS names, IP addresses, and fully qualified domain names are allowed. -The default is the local computer. -Use localhost or a dot ('.') to specify the local computer explicitly. + +Specifies one or more Hyper-V hosts that run this cmdlet. NetBIOS names, IP addresses, and fully +qualified domain names are allowed. The default is the local computer. Use localhost or a dot (`.`) +to specify the local computer explicitly. ```yaml Type: String[] @@ -91,7 +108,9 @@ Accept wildcard characters: False ``` ### -Credential -Specifies one or more user accounts that have permission to perform this action. The default is the current user. + +Specifies one or more user accounts that have permission to perform this action. The default is the +current user. ```yaml Type: PSCredential[] @@ -106,6 +125,7 @@ Accept wildcard characters: False ``` ### -Name + Specifies the name of the graphic processing unit to be retrieved. ```yaml @@ -121,7 +141,11 @@ Accept wildcard characters: False ``` ### CommonParameters -This cmdlet supports the common parameters: -Debug, -ErrorAction, -ErrorVariable, -InformationAction, -InformationVariable, -OutVariable, -OutBuffer, -PipelineVariable, -Verbose, -WarningAction, and -WarningVariable. For more information, see [about_CommonParameters](https://go.microsoft.com/fwlink/?LinkID=113216). + +This cmdlet supports the common parameters: -Debug, -ErrorAction, -ErrorVariable, +-InformationAction, -InformationVariable, -OutVariable, -OutBuffer, -PipelineVariable, -Verbose, +-WarningAction, and -WarningVariable. For more information, see +[about_CommonParameters](/powershell/module/microsoft.powershell.core/about/about_commonparameters). ## INPUTS @@ -134,3 +158,5 @@ This cmdlet supports the common parameters: -Debug, -ErrorAction, -ErrorVariable ## NOTES ## RELATED LINKS + +[Set-VMHostPartitionableGpu](set-vmhostpartitionablegpu.md) diff --git a/docset/winserver2025-ps/hyper-v/Get-VMNetworkAdapter.md b/docset/winserver2025-ps/hyper-v/Get-VMNetworkAdapter.md index dd23bd621a..2c816c8876 100644 --- a/docset/winserver2025-ps/hyper-v/Get-VMNetworkAdapter.md +++ b/docset/winserver2025-ps/hyper-v/Get-VMNetworkAdapter.md @@ -203,7 +203,7 @@ Accept wildcard characters: False ### -VM Specifies the virtual machine whose virtual network adapters are to be retrieved. -. The asterisk, "*", is the wildcard. +The asterisk, "*", is the wildcard. If it is specified the cmdlet returns virtual network adapters from every virtual machine in the system. ```yaml diff --git a/docset/winserver2025-ps/hyper-v/Hyper-V.md b/docset/winserver2025-ps/hyper-v/Hyper-V.md index a78f953d39..32b28c8a90 100644 --- a/docset/winserver2025-ps/hyper-v/Hyper-V.md +++ b/docset/winserver2025-ps/hyper-v/Hyper-V.md @@ -5,7 +5,7 @@ Help Version: 5.0.2.1 Locale: en-US Module Guid: af4bddd0-8583-4ff2-84b2-a33f5c8de8a7 Module Name: Hyper-V -ms.date: 12/20/2016 +ms.date: 06/12/2024 title: Hyper-V --- # Hyper-V Module @@ -16,6 +16,9 @@ This reference provides cmdlet descriptions and syntax for all Hyper-V-specific ## Hyper-V Cmdlets +### [Add-VMAssignableDevice](./Add-VMAssignableDevice.md) +Adds an assignable device to a specific virtual machine. + ### [Add-VMDvdDrive](./Add-VMDvdDrive.md) Adds a DVD drive to a virtual machine. @@ -31,6 +34,9 @@ Adds group members to a virtual machine group. ### [Add-VMHardDiskDrive](./Add-VMHardDiskDrive.md) Adds a hard disk drive to a virtual machine. +### [Add-VMHostAssignableDevice](./Add-VMHostAssignableDevice.md) +Adds an assignable device to a virtual machine (VM) host. + ### [Add-VMMigrationNetwork](./Add-VMMigrationNetwork.md) Adds a network for virtual machine migration on one or more virtual machine hosts. @@ -124,6 +130,9 @@ Removes a host bus adapter from a virtual storage area network (SAN). ### [Dismount-VHD](./Dismount-VHD.md) Dismounts a virtual hard disk. +### [Dismount-VMHostAssignableDevice](./Dismount-VMHostAssignableDevice.md) +Dismounts a device from a virtual machine (VM) host. + ### [Enable-VMConsoleSupport](./Enable-VMConsoleSupport.md) Enables keyboard, video, and mouse for virtual machines. @@ -169,6 +178,9 @@ Gets information about a checkpoint in a VHD set. ### [Get-VM](./Get-VM.md) Gets the virtual machines from one or more Hyper-V hosts. +### [Get-VMAssignableDevice](./Get-VMAssignableDevice.md) +Retrieves information about the assignable device from a specific virtual machine. + ### [Get-VMBios](./Get-VMBios.md) Gets the BIOS of a virtual machine or snapshot. @@ -202,6 +214,9 @@ Gets the virtual hard disk drives attached to one or more virtual machines. ### [Get-VMHost](./Get-VMHost.md) Gets a Hyper-V host. +### [Get-VMHostAssignableDevice](./Get-VMHostAssignableDevice.md) +Retrieves device information assigned to a virtual machine (VM) host. + ### [Get-VMHostCluster](./Get-VMHostCluster.md) Gets virtual machine host clusters. @@ -252,7 +267,6 @@ Gets members of a routing domain. ### [Get-VMNetworkAdapterTeamMapping](./Get-VMNetworkAdapterTeamMapping.md) - ### [Get-VMNetworkAdapterVlan](./Get-VMNetworkAdapterVlan.md) Gets the virtual LAN settings configured on a virtual network adapter. @@ -349,6 +363,9 @@ Merges virtual hard disks. ### [Mount-VHD](./Mount-VHD.md) Mounts one or more virtual hard disks. +### [Mount-VMHostAssignableDevice](./Mount-VMHostAssignableDevice.md) +Mounts a device to a virtual machine (VM) host. + ### [Move-VM](./Move-VM.md) Moves a virtual machine to a new Hyper-V host. @@ -391,6 +408,9 @@ Removes a checkpoint from a VHD set file. ### [Remove-VM](./Remove-VM.md) Deletes a virtual machine. +### [Remove-VMAssignableDevice](./Remove-VMAssignableDevice.md) +Removes information about the assignable devices from a specific virtual machine. + ### [Remove-VMDvdDrive](./Remove-VMDvdDrive.md) Deletes a DVD drive from a virtual machine. @@ -409,6 +429,9 @@ Removes members from a virtual machine group. ### [Remove-VMHardDiskDrive](./Remove-VMHardDiskDrive.md) Deletes a hard disk drive from a virtual machine. +### [Remove-VMHostAssignableDevice](./Remove-VMHostAssignableDevice.md) +Removes a device assigned to a virtual machine (VM) host. + ### [Remove-VMMigrationNetwork](./Remove-VMMigrationNetwork.md) Removes a network from use with migration. @@ -426,7 +449,6 @@ Removes a routing domain from a virtual network adapter. ### [Remove-VMNetworkAdapterTeamMapping](./Remove-VMNetworkAdapterTeamMapping.md) - ### [Remove-VMRemoteFx3dVideoAdapter](./Remove-VMRemoteFx3dVideoAdapter.md) Removes a RemoteFX 3D video adapter from a virtual machine. @@ -579,7 +601,6 @@ Sets virtual subnets on a routing domain. ### [Set-VMNetworkAdapterTeamMapping](./Set-VMNetworkAdapterTeamMapping.md) - ### [Set-VMNetworkAdapterVlan](./Set-VMNetworkAdapterVlan.md) Configures the virtual LAN settings for the traffic through a virtual network adapter. diff --git a/docset/winserver2025-ps/hyper-v/Mount-VMHostAssignableDevice.md b/docset/winserver2025-ps/hyper-v/Mount-VMHostAssignableDevice.md new file mode 100644 index 0000000000..da5e197134 --- /dev/null +++ b/docset/winserver2025-ps/hyper-v/Mount-VMHostAssignableDevice.md @@ -0,0 +1,232 @@ +--- +description: Mounts an assignable device to a virtual machine host. +external help file: Microsoft.HyperV.PowerShell.Cmdlets.dll-Help.xml +Module Name: Hyper-V +ms.date: 06/12/2024 +online version: https://learn.microsoft.com/powershell/module/hyper-v/mount-vmhostassignabledevice?view=windowsserver2025-ps&wt.mc_id=ps-gethelp +schema: 2.0.0 +title: Mount-VMHostAssignableDevice +--- + +# Mount-VMHostAssignableDevice + +## SYNOPSIS +Mounts a device to a virtual machine (VM) host. + +## SYNTAX + +### Path (Default) + +``` +Mount-VMHostAssignableDevice [-CimSession ] [-ComputerName ] + [-Credential ] [-InstancePath ] [-LocationPath ] [-Passthru] + [-WhatIf] [-Confirm] [] +``` + +### Object + +``` +Mount-VMHostAssignableDevice [-HostAssignableDevice] [-Passthru] + [-WhatIf] [-Confirm] [] +``` + +## DESCRIPTION + +The `Mount-VMHostAssignableDevice` cmdlet mounts a device such as GPUs, network adapters, or storage +controllers that are physically present on the virtual machine host. + +## EXAMPLES + +### Example 1 + +```powershell +$device = Get-VMHostAssignableDevice -InstancePath "PCIROOT(0)#PCI(0300)#PCI(0000)" +$params = @{ +HostAssignableDevice = $device +VMName = "MyVM" +} +Mount-VMHostAssignableDevice @params +``` + +In this example, the `Get-VMHostAssignableDevice` cmdlet retrieves the device with the specified +instance path and stores it in the `$device` variable. The `Mount-VMHostAssignableDevice` cmdlet +then assigns this device to the virtual machine named **MyVM**. + +## PARAMETERS + +### -CimSession + +Runs the cmdlet in a remote session or on a remote computer. Enter a computer name or a session +object, such as the output of a [New-CimSession](/powershell/module/cimcmdlets/new-cimsession) +or [Get-CimSession](/powershell/module/cimcmdlets/get-cimsession) cmdlet. The default is the +current session on the local computer. + +```yaml +Type: CimSession[] +Parameter Sets: Path +Aliases: + +Required: False +Position: Named +Default value: None +Accept pipeline input: False +Accept wildcard characters: False +``` + +### -ComputerName + +Specifies one or more Hyper-V hosts from which the assignable devices are to be mounted. NetBIOS +names, IP addresses, and fully qualified domain names are allowed. The default is the local +computer. Use localhost or a dot (`.`) to specify the local computer explicitly. + +```yaml +Type: String[] +Parameter Sets: Path +Aliases: + +Required: False +Position: Named +Default value: None +Accept pipeline input: False +Accept wildcard characters: False +``` + +### -Credential + +Specifies one or more user accounts that have permission to perform this action. The default is the +current user. + +```yaml +Type: PSCredential[] +Parameter Sets: Path +Aliases: + +Required: False +Position: Named +Default value: None +Accept pipeline input: False +Accept wildcard characters: False +``` + +### -HostAssignableDevice + +Specifies the assignable device to be mounted on the virtual machine host. + +```yaml +Type: VMHostAssignableDevice[] +Parameter Sets: Object +Aliases: VMHostAssignableDevice + +Required: True +Position: 0 +Default value: None +Accept pipeline input: True (ByValue) +Accept wildcard characters: False +``` + +### -InstancePath + +Represents the Device Instance path in the host machine. + +```yaml +Type: String +Parameter Sets: Path +Aliases: + +Required: False +Position: Named +Default value: None +Accept pipeline input: False +Accept wildcard characters: False +``` + +### -LocationPath + +Specifies the location path to the assignable device. + +```yaml +Type: String +Parameter Sets: Path +Aliases: + +Required: False +Position: Named +Default value: None +Accept pipeline input: False +Accept wildcard characters: False +``` + +### -Passthru + +Returns an object for each process that the cmdlet started. + +```yaml +Type: SwitchParameter +Parameter Sets: (All) +Aliases: + +Required: False +Position: Named +Default value: None +Accept pipeline input: False +Accept wildcard characters: False +``` + +### -Confirm + +Prompts you for confirmation before running the cmdlet. + +```yaml +Type: SwitchParameter +Parameter Sets: (All) +Aliases: cf + +Required: False +Position: Named +Default value: None +Accept pipeline input: False +Accept wildcard characters: False +``` + +### -WhatIf + +Shows what would happen if the cmdlet runs. The cmdlet is not run. + +```yaml +Type: SwitchParameter +Parameter Sets: (All) +Aliases: wi + +Required: False +Position: Named +Default value: None +Accept pipeline input: False +Accept wildcard characters: False +``` + +### CommonParameters + +This cmdlet supports the common parameters: -Debug, -ErrorAction, -ErrorVariable, +-InformationAction, -InformationVariable, -OutVariable, -OutBuffer, -PipelineVariable, -Verbose, +-WarningAction, and -WarningVariable. For more information, see +[about_CommonParameters](/powershell/module/microsoft.powershell.core/about/about_commonparameters). + +## INPUTS + +### Microsoft.HyperV.PowerShell.VMHostAssignableDevice[] + +## OUTPUTS + +### Microsoft.HyperV.PowerShell.VMHostAssignableDevice + +## NOTES + +## RELATED LINKS + +[Add-VMHostAssignableDevice](add-vmhostassignabledevice.md) + +[Get-VMHostAssignableDevice](get-vmhostassignabledevice.md) + +[Dismount-VMHostAssignableDevice](dismount-vmhostassignabledevice.md) + +[Remove-VMHostAssignableDevice](remove-vmhostassignabledevice.md) diff --git a/docset/winserver2025-ps/hyper-v/Remove-VMAssignableDevice.md b/docset/winserver2025-ps/hyper-v/Remove-VMAssignableDevice.md new file mode 100644 index 0000000000..4f768144a3 --- /dev/null +++ b/docset/winserver2025-ps/hyper-v/Remove-VMAssignableDevice.md @@ -0,0 +1,257 @@ +--- +description: Removes a device assigned to a virtual machine. +external help file: Microsoft.HyperV.PowerShell.Cmdlets.dll-Help.xml +Module Name: Hyper-V +ms.date: 06/12/2024 +online version: https://learn.microsoft.com/powershell/module/hyper-v/remove-vmassignabledevice?view=windowsserver2025-ps&wt.mc_id=ps-gethelp +schema: 2.0.0 +title: Remove-VMAssignableDevice +--- + +# Remove-VMAssignableDevice + +## SYNOPSIS +Removes information about the assignable devices from a specific virtual machine. + +## SYNTAX + +### VMName (Default) + +``` +Remove-VMAssignableDevice [-CimSession ] [-ComputerName ] + [-Credential ] [-VMName] [-InstancePath ] + [-LocationPath ] [-Passthru] [-WhatIf] [-Confirm] [] +``` + +### Object + +``` +Remove-VMAssignableDevice [-VMAssignableDevice] [-Passthru] [-WhatIf] + [-Confirm] [] +``` + +## DESCRIPTION + +The `Remove-VMAssignableDevice` cmdlet removes an assignable device from a specified virtual +machine (VM). This is often used in scenarios where a physical device, such as a GPU or network +adapter, was previously assigned to a VM and needs to be unassigned. + +## EXAMPLES + +### Example 1 + +```powershell +$params = @{ +VMName = "MyVM" +InstancePath = "PCIROOT(0)#PCI(0300)#PCI(0000)#PCI(0800)#PCI(0000)#PCI(1000)" +} +Remove-VMAssignableDevice $params +``` + +This example removes a specific assignable device, identified by its instance path, from the +virtual machine named **MyVM**. + +### Example 2 + +```powershell +$params = @{ +VMName = "MyVM" +} +$vm = Get-VMAssignableDevice @params | Where-Object { $_.ResourcePoolName -eq "GpuChildPool" } +$vm | Remove-VMAssignableDevice +``` + +This example removes a specific assignable device, identified by the ResourcePoolName property +**GpuChildPool**, from the virtual machine named **MyVM**. + +## PARAMETERS + +### -CimSession + +Runs the cmdlet in a remote session or on a remote computer. Enter a computer name or a session +object, such as the output of a [New-CimSession](/powershell/module/cimcmdlets/new-cimsession) +or [Get-CimSession](/powershell/module/cimcmdlets/get-cimsession) cmdlet. The default is the +current session on the local computer. + +```yaml +Type: CimSession[] +Parameter Sets: VMName +Aliases: + +Required: False +Position: Named +Default value: None +Accept pipeline input: False +Accept wildcard characters: False +``` + +### -ComputerName + +Specifies one or more Hyper-V hosts on the virtual network adapters are to be retrieved. NetBIOS +names, IP addresses, and fully qualified domain names are allowed. The default is the local +computer. Use localhost or a dot (`.`) to specify the local computer explicitly. + +```yaml +Type: String[] +Parameter Sets: VMName +Aliases: + +Required: False +Position: Named +Default value: None +Accept pipeline input: False +Accept wildcard characters: False +``` + +### -Credential + +Specifies one or more user accounts that have permission to perform this action. The default is the +current user. + +```yaml +Type: PSCredential[] +Parameter Sets: VMName +Aliases: + +Required: False +Position: Named +Default value: None +Accept pipeline input: False +Accept wildcard characters: False +``` + +### -InstancePath + +Removes the Device Instance path in the host machine. + +```yaml +Type: String +Parameter Sets: VMName +Aliases: + +Required: False +Position: Named +Default value: None +Accept pipeline input: False +Accept wildcard characters: False +``` + +### -LocationPath + +Specifies the location path to the assignable device. + +```yaml +Type: String +Parameter Sets: VMName +Aliases: + +Required: False +Position: Named +Default value: None +Accept pipeline input: False +Accept wildcard characters: False +``` + +### -Passthru + +Returns an object for each process that the cmdlet started. + +```yaml +Type: SwitchParameter +Parameter Sets: (All) +Aliases: + +Required: False +Position: Named +Default value: None +Accept pipeline input: False +Accept wildcard characters: False +``` + +### -VMAssignableDevice + +Specifies the assignable device object that you want to remove from the virtual machine. This is +usually an object retrieved from a cmdlet like `Get-VMAssignableDevice`. + +```yaml +Type: VMAssignedDevice[] +Parameter Sets: Object +Aliases: + +Required: True +Position: 0 +Default value: None +Accept pipeline input: True (ByValue) +Accept wildcard characters: False +``` + +### -VMName + +Specifies the name of the virtual machine from which you want to remove the assignable device. + +```yaml +Type: String[] +Parameter Sets: VMName +Aliases: + +Required: True +Position: 0 +Default value: None +Accept pipeline input: False +Accept wildcard characters: False +``` + +### -Confirm + +Prompts you for confirmation before running the cmdlet. + +```yaml +Type: SwitchParameter +Parameter Sets: (All) +Aliases: cf + +Required: False +Position: Named +Default value: None +Accept pipeline input: False +Accept wildcard characters: False +``` + +### -WhatIf + +Shows what would happen if the cmdlet runs. The cmdlet is not run. + +```yaml +Type: SwitchParameter +Parameter Sets: (All) +Aliases: wi + +Required: False +Position: Named +Default value: None +Accept pipeline input: False +Accept wildcard characters: False +``` + +### CommonParameters + +This cmdlet supports the common parameters: -Debug, -ErrorAction, -ErrorVariable, +-InformationAction, -InformationVariable, -OutVariable, -OutBuffer, -PipelineVariable, -Verbose, +-WarningAction, and -WarningVariable. For more information, see +[about_CommonParameters](/powershell/module/microsoft.powershell.core/about/about_commonparameters). + +## INPUTS + +### Microsoft.HyperV.PowerShell.VMAssignedDevice[] + +## OUTPUTS + +### Microsoft.HyperV.PowerShell.VMAssignedDevice + +## NOTES + +## RELATED LINKS + +[Add-VMAssignableDevice](add-vmassignabledevice.md) + +[Get-VMAssignableDevice](get-vmassignabledevice.md) diff --git a/docset/winserver2025-ps/hyper-v/Remove-VMGpuPartitionAdapter.md b/docset/winserver2025-ps/hyper-v/Remove-VMGpuPartitionAdapter.md index 052bd5e136..aa20c6541f 100644 --- a/docset/winserver2025-ps/hyper-v/Remove-VMGpuPartitionAdapter.md +++ b/docset/winserver2025-ps/hyper-v/Remove-VMGpuPartitionAdapter.md @@ -2,7 +2,7 @@ description: Removes an assigned GPU partition from a virtual machine. external help file: Microsoft.HyperV.PowerShell.Cmdlets.dll-Help.xml Module Name: Hyper-V -ms.date: 09/22/2022 +ms.date: 06/12/2024 online version: https://learn.microsoft.com/powershell/module/hyper-v/remove-vmgpupartitionadapter?view=windowsserver2025-ps&wt.mc_id=ps-gethelp schema: 2.0.0 title: Remove-VMGpuPartitionAdapter @@ -16,30 +16,36 @@ Removes an assigned GPU partition from a virtual machine. ## SYNTAX ### VMName (Default) + ``` Remove-VMGpuPartitionAdapter [-CimSession ] [-ComputerName ] - [-Credential ] [-VMName] [-Passthru] [-AdapterId ] [-WhatIf] [-Confirm] - [] + [-Credential ] [-VMName] [-Passthru] [-AdapterId ] [-WhatIf] + [-Confirm] [] ``` ### VMObject + ``` -Remove-VMGpuPartitionAdapter [-VM] [-Passthru] [-AdapterId ] [-WhatIf] [-Confirm] - [] +Remove-VMGpuPartitionAdapter [-VM] [-Passthru] [-AdapterId ] [-WhatIf] + [-Confirm] [] ``` ### Object + ``` -Remove-VMGpuPartitionAdapter [-VMGpuPartitionAdapter] [-Passthru] [-WhatIf] - [-Confirm] [] +Remove-VMGpuPartitionAdapter [-VMGpuPartitionAdapter] [-Passthru] + [-WhatIf] [-Confirm] [] ``` ## DESCRIPTION -The 'Remove-VMGpuPartitionAdapter' cmdlet removes an assigned graphic processing unit partition from a virtual machine and releases that partition back to the host GPU. + +The `Remove-VMGpuPartitionAdapter` cmdlet removes an assigned graphic processing unit partition from +a virtual machine and releases that partition back to the host GPU. ## EXAMPLES ### Example 1 + ```powershell $testvm = Get-VM "TestVM" Remove-VMGpuPartitionAdapter -VM $testvm @@ -48,6 +54,7 @@ Remove-VMGpuPartitionAdapter -VM $testvm This example removes a partition assigned to a specific VM object. ### Example 2 + ```powershell $testvm = Get-VM "TestVM" $GPUpartition = Get-VMGpuPartitionAdapter -VM $testvm @@ -59,7 +66,8 @@ This example removes a specific partition object from a specific VM. ## PARAMETERS ### -AdapterId -This is a VM's GPU partition identification number used to remove a GPU from a VM. + +This is a VM's GPU partition identification number used to remove a GPU from a VM. ```yaml Type: String @@ -74,9 +82,11 @@ Accept wildcard characters: False ``` ### -CimSession -Runs the cmdlet in a remote session or on a remote computer. -Enter a computer name or a session object, such as the output of a [New-CimSession](https://go.microsoft.com/fwlink/p/?LinkId=227967) or [Get-CimSession](https://go.microsoft.com/fwlink/p/?LinkId=227966) cmdlet. -The default is the current session on the local computer. + +Runs the cmdlet in a remote session or on a remote computer. Enter a computer name or a session +object, such as the output of a [New-CimSession](/powershell/module/cimcmdlets/new-cimsession) +or [Get-CimSession](/powershell/module/cimcmdlets/get-cimsession) cmdlet. The default is the +current session on the local computer. ```yaml Type: CimSession[] @@ -91,8 +101,10 @@ Accept wildcard characters: False ``` ### -ComputerName -Specifies one or more Hyper-V hosts on the virtual network adapters are to be retrieved. NetBIOS names, IP addresses, and fully qualified domain names are allowed. -The default is the local computer.Use localhost or a dot ('.') to specify the local computer explicitly. + +Specifies one or more Hyper-V hosts on the virtual network adapters are to be retrieved. NetBIOS +names, IP addresses, and fully qualified domain names are allowed. The default is the local +computer.Use localhost or a dot (`.`) to specify the local computer explicitly. ```yaml Type: String[] @@ -107,7 +119,9 @@ Accept wildcard characters: False ``` ### -Credential -Specifies one or more user accounts that have permission to perform this action. The default is the current user. + +Specifies one or more user accounts that have permission to perform this action. The default is the +current user. ```yaml Type: PSCredential[] @@ -122,6 +136,7 @@ Accept wildcard characters: False ``` ### -Passthru + Returns an object for each process that the cmdlet started. ```yaml @@ -137,6 +152,7 @@ Accept wildcard characters: False ``` ### -VM + Specifies the virtual machine whose virtual network adapters are to be retrieved. The asterisk (`*`) is the wildcard. If it is specified the cmdlet returns virtual network adapters from every virtual machine in the system. @@ -154,7 +170,8 @@ Accept wildcard characters: False ``` ### -VMGpuPartitionAdapter -GPU partition object obtained from 'Get-VMGpuPartitionAdapter'. + +GPU partition object obtained from `Get-VMGpuPartitionAdapter`. ```yaml Type: VMGpuPartitionAdapter[] @@ -169,7 +186,8 @@ Accept wildcard characters: False ``` ### -VMName -Specifies the name of the virtual machine whose network adapters are to be retrieved. + +Specifies the name of the virtual machine whose network adapters are to be removed. ```yaml Type: String[] @@ -184,6 +202,7 @@ Accept wildcard characters: False ``` ### -Confirm + Prompts you for confirmation before running the cmdlet. ```yaml @@ -199,8 +218,8 @@ Accept wildcard characters: False ``` ### -WhatIf -Shows what would happen if the cmdlet runs. -The cmdlet is not run. + +Shows what would happen if the cmdlet runs. The cmdlet is not run. ```yaml Type: SwitchParameter @@ -215,7 +234,11 @@ Accept wildcard characters: False ``` ### CommonParameters -This cmdlet supports the common parameters: -Debug, -ErrorAction, -ErrorVariable, -InformationAction, -InformationVariable, -OutVariable, -OutBuffer, -PipelineVariable, -Verbose, -WarningAction, and -WarningVariable. For more information, see [about_CommonParameters](https://go.microsoft.com/fwlink/?LinkID=113216). + +This cmdlet supports the common parameters: -Debug, -ErrorAction, -ErrorVariable, +-InformationAction, -InformationVariable, -OutVariable, -OutBuffer, -PipelineVariable, -Verbose, +-WarningAction, and -WarningVariable. For more information, see +[about_CommonParameters](/powershell/module/microsoft.powershell.core/about/about_commonparameters). ## INPUTS @@ -230,3 +253,9 @@ This cmdlet supports the common parameters: -Debug, -ErrorAction, -ErrorVariable ## NOTES ## RELATED LINKS + +[Add-VMGpuPartitionAdapter](add-vmgpupartitionadapter.md) + +[Get-VMGpuPartitionAdapter](get-vmgpupartitionadapter.md) + +[Set-VMGpuPartitionAdapter](set-vmgpupartitionadapter.md) diff --git a/docset/winserver2025-ps/hyper-v/Remove-VMHostAssignableDevice.md b/docset/winserver2025-ps/hyper-v/Remove-VMHostAssignableDevice.md new file mode 100644 index 0000000000..1fbb70bdab --- /dev/null +++ b/docset/winserver2025-ps/hyper-v/Remove-VMHostAssignableDevice.md @@ -0,0 +1,248 @@ +--- +description: Removes an assignable device from a virtual machine host. +external help file: Microsoft.HyperV.PowerShell.Cmdlets.dll-Help.xml +Module Name: Hyper-V +ms.date: 06/12/2024 +online version: https://learn.microsoft.com/powershell/module/hyper-v/remove-vmhostassignabledevice?view=windowsserver2025-ps&wt.mc_id=ps-gethelp +schema: 2.0.0 +title: Remove-VMHostAssignableDevice +--- + +# Remove-VMHostAssignableDevice + +## SYNOPSIS +Removes a device assigned to a virtual machine (VM) host. + +## SYNTAX + +### Path (Default) + +``` +Remove-VMHostAssignableDevice [-CimSession ] [-ComputerName ] + [-Credential ] [-InstancePath ] [-LocationPath ] + -ResourcePoolName [-Force] [-WhatIf] [-Confirm] [] +``` + +### Object + +``` +Remove-VMHostAssignableDevice [-HostAssignableDevice] + -ResourcePoolName [-Force] [-WhatIf] [-Confirm] [] +``` + +## DESCRIPTION + +The `Remove-VMHostAssignableDevice` cmdlet removes a device that is assigned to a virtual machine +host. Depending on the parameters specified, you can remove devices by providing either the +instance or location path of the device. + +## EXAMPLES + +### Example 1 + +```powershell +$params = @{ +InstancePath = "PCIROOT(0)#PCI(0300)#PCI(0000)" +ResourcePoolName = "MyResourcePool" +} +Remove-VMHostAssignableDevice $params +``` + +This example removes the device with the specified instance path from the resource pool named +**MyResourcePool**. + +## PARAMETERS + +### -CimSession + +Runs the cmdlet in a remote session or on a remote computer. Enter a computer name or a session +object, such as the output of a [New-CimSession](/powershell/module/cimcmdlets/new-cimsession) +or [Get-CimSession](/powershell/module/cimcmdlets/get-cimsession) cmdlet. The default is the +current session on the local computer. + +```yaml +Type: CimSession[] +Parameter Sets: Path +Aliases: + +Required: False +Position: Named +Default value: None +Accept pipeline input: False +Accept wildcard characters: False +``` + +### -ComputerName + +Specifies one or more Hyper-V hosts from which the assignable devices are to be removed. NetBIOS +names, IP addresses, and fully qualified domain names are allowed. The default is the local +computer. Use localhost or a dot (`.`) to specify the local computer explicitly. + +```yaml +Type: String[] +Parameter Sets: Path +Aliases: + +Required: False +Position: Named +Default value: None +Accept pipeline input: False +Accept wildcard characters: False +``` + +### -Credential + +Specifies one or more user accounts that have permission to perform this action. The default is the +current user. + +```yaml +Type: PSCredential[] +Parameter Sets: Path +Aliases: + +Required: False +Position: Named +Default value: None +Accept pipeline input: False +Accept wildcard characters: False +``` + +### -Force + +Forces the command to run without asking for user confirmation. + +```yaml +Type: SwitchParameter +Parameter Sets: (All) +Aliases: + +Required: False +Position: Named +Default value: None +Accept pipeline input: False +Accept wildcard characters: False +``` + +### -HostAssignableDevice + +Specifies the device object to be removed. You can get this object using +`Get-VMHostAssignableDevice`. + +```yaml +Type: VMHostAssignableDevice[] +Parameter Sets: Object +Aliases: VMHostAssignableDevice + +Required: True +Position: 0 +Default value: None +Accept pipeline input: True (ByValue) +Accept wildcard characters: False +``` + +### -InstancePath + +Specifies the Device Instance path in the host machine. + +```yaml +Type: String +Parameter Sets: Path +Aliases: + +Required: False +Position: Named +Default value: None +Accept pipeline input: False +Accept wildcard characters: False +``` + +### -LocationPath + +Specifies the location path to the assignable device. + +```yaml +Type: String +Parameter Sets: Path +Aliases: + +Required: False +Position: Named +Default value: None +Accept pipeline input: False +Accept wildcard characters: False +``` + +### -ResourcePoolName + +Specifies the name of the resource pool from which to remove an assignable device. + +```yaml +Type: String[] +Parameter Sets: (All) +Aliases: + +Required: True +Position: Named +Default value: None +Accept pipeline input: False +Accept wildcard characters: False +``` + +### -Confirm + +Prompts you for confirmation before running the cmdlet. + +```yaml +Type: SwitchParameter +Parameter Sets: (All) +Aliases: cf + +Required: False +Position: Named +Default value: None +Accept pipeline input: False +Accept wildcard characters: False +``` + +### -WhatIf + +Shows what would happen if the cmdlet runs. The cmdlet is not run. + +```yaml +Type: SwitchParameter +Parameter Sets: (All) +Aliases: wi + +Required: False +Position: Named +Default value: None +Accept pipeline input: False +Accept wildcard characters: False +``` + +### CommonParameters + +This cmdlet supports the common parameters: -Debug, -ErrorAction, -ErrorVariable, +-InformationAction, -InformationVariable, -OutVariable, -OutBuffer, -PipelineVariable, -Verbose, +-WarningAction, and -WarningVariable. For more information, see +[about_CommonParameters](/powershell/module/microsoft.powershell.core/about/about_commonparameters). + +## INPUTS + +### Microsoft.HyperV.PowerShell.VMHostAssignableDevice[] + +## OUTPUTS + +### System.Object + +## NOTES + +## RELATED LINKS + +[Add-VMHostAssignableDevice](add-vmhostassignabledevice.md) + +[Get-VMHostAssignableDevice](get-vmhostassignabledevice.md) + +[Dismount-VMHostAssignableDevice](dismount-vmhostassignabledevice.md) + +[Mount-VMHostAssignableDevice](mount-vmhostassignabledevice.md) diff --git a/docset/winserver2025-ps/hyper-v/Set-VMGpuPartitionAdapter.md b/docset/winserver2025-ps/hyper-v/Set-VMGpuPartitionAdapter.md index 42f57e5749..923ae500ce 100644 --- a/docset/winserver2025-ps/hyper-v/Set-VMGpuPartitionAdapter.md +++ b/docset/winserver2025-ps/hyper-v/Set-VMGpuPartitionAdapter.md @@ -2,7 +2,7 @@ description: Assigns a partition of a GPU to a virtual machine. external help file: Microsoft.HyperV.PowerShell.Cmdlets.dll-Help.xml Module Name: Hyper-V -ms.date: 09/22/2022 +ms.date: 06/12/2024 online version: https://learn.microsoft.com/powershell/module/hyper-v/set-vmgpupartitionadapter?view=windowsserver2025-ps&wt.mc_id=ps-gethelp schema: 2.0.0 title: Set-VMGpuPartitionAdapter @@ -16,44 +16,51 @@ Assigns a partition of a GPU to a virtual machine. ## SYNTAX ### VMName (Default) + ``` Set-VMGpuPartitionAdapter [-CimSession ] [-ComputerName ] [-Credential ] [-VMName] [-Passthru] [-AdapterId ] [-MinPartitionVRAM ] [-MaxPartitionVRAM ] [-OptimalPartitionVRAM ] [-MinPartitionEncode ] [-MaxPartitionEncode ] [-OptimalPartitionEncode ] [-MinPartitionDecode ] [-MaxPartitionDecode ] [-OptimalPartitionDecode ] - [-MinPartitionCompute ] [-MaxPartitionCompute ] [-OptimalPartitionCompute ] [-WhatIf] - [-Confirm] [] + [-MinPartitionCompute ] [-MaxPartitionCompute ] [-OptimalPartitionCompute ] + [-WhatIf] [-Confirm] [] ``` ### VMObject + ``` Set-VMGpuPartitionAdapter [-VM] [-Passthru] [-AdapterId ] [-MinPartitionVRAM ] [-MaxPartitionVRAM ] [-OptimalPartitionVRAM ] [-MinPartitionEncode ] [-MaxPartitionEncode ] [-OptimalPartitionEncode ] [-MinPartitionDecode ] [-MaxPartitionDecode ] [-OptimalPartitionDecode ] - [-MinPartitionCompute ] [-MaxPartitionCompute ] [-OptimalPartitionCompute ] [-WhatIf] - [-Confirm] [] + [-MinPartitionCompute ] [-MaxPartitionCompute ] [-OptimalPartitionCompute ] + [-WhatIf] [-Confirm] [] ``` ### Object + ``` Set-VMGpuPartitionAdapter [-VMGpuPartitionAdapter] [-Passthru] [-MinPartitionVRAM ] [-MaxPartitionVRAM ] [-OptimalPartitionVRAM ] [-MinPartitionEncode ] [-MaxPartitionEncode ] [-OptimalPartitionEncode ] [-MinPartitionDecode ] [-MaxPartitionDecode ] [-OptimalPartitionDecode ] - [-MinPartitionCompute ] [-MaxPartitionCompute ] [-OptimalPartitionCompute ] [-WhatIf] - [-Confirm] [] + [-MinPartitionCompute ] [-MaxPartitionCompute ] [-OptimalPartitionCompute ] + [-WhatIf] [-Confirm] [] ``` ## DESCRIPTION -The 'Set-VMGpuPartitionAdapter' cmdlet assigns a partition of a GPU to a virtual machine. Running the command against a virtual machine assigns a full partition. Additional parameters exist to assign more specific options to a VM. + +The `Set-VMGpuPartitionAdapter` cmdlet assigns a partition of a GPU to a virtual machine. Running +the command against a virtual machine assigns a full partition. Additional parameters exist to +assign more specific options to a VM. ## EXAMPLES ### Example 1 + ```powershell -$vm = get-vm test +$vm = Get-VM "Test" Set-VMGpuPartitionAdapter -VM $vm ``` @@ -62,6 +69,7 @@ This example assign a partition to a VM passing a VM object. ## PARAMETERS ### -AdapterId + A VM's GPU partition identification number used to display the GPU information assigned to a VM. ```yaml @@ -77,8 +85,11 @@ Accept wildcard characters: False ``` ### -CimSession -Runs the cmdlet in a remote session or on a remote computer. Enter a computer name or a session object, such as the output of a [New-CimSession](https://go.microsoft.com/fwlink/p/?LinkId=227967) or [Get-CimSession](https://go.microsoft.com/fwlink/p/?LinkId=227966) cmdlet. -The default is the current session on the local computer. + +Runs the cmdlet in a remote session or on a remote computer. Enter a computer name or a session +object, such as the output of a [New-CimSession](/powershell/module/cimcmdlets/new-cimsession) +or [Get-CimSession](/powershell/module/cimcmdlets/get-cimsession) cmdlet. The default is the +current session on the local computer. ```yaml Type: CimSession[] @@ -93,9 +104,10 @@ Accept wildcard characters: False ``` ### -ComputerName -Specifies one or more Hyper-V hosts on the virtual network adapters are to be retrieved. NetBIOS names, IP addresses, and fully qualified domain names are allowed. -The default is the local computer. -Use localhost or a dot ('.') to specify the local computer explicitly. + +Specifies one or more Hyper-V hosts on the virtual network adapters are to be retrieved. NetBIOS +names, IP addresses, and fully qualified domain names are allowed. The default is the local +computer. Use localhost or a dot (`.`) to specify the local computer explicitly. ```yaml Type: String[] @@ -110,8 +122,9 @@ Accept wildcard characters: False ``` ### -Credential -Specifies one or more user accounts that have permission to perform this action. -The default is the current user. + +Specifies one or more user accounts that have permission to perform this action. The default is the +current user. ```yaml Type: PSCredential[] @@ -126,7 +139,9 @@ Accept wildcard characters: False ``` ### -MaxPartitionCompute -The maximum number of compute assigned by the host GPU. This is defined by the manufacturer's driver. + +The maximum number of compute assigned by the host GPU. This is defined by the manufacturer's +driver. ```yaml Type: UInt64 @@ -141,7 +156,9 @@ Accept wildcard characters: False ``` ### -MaxPartitionDecode -The maximum number of decoders assigned by the host GPU. This is defined by the manufacturer's driver. + +The maximum number of decoders assigned by the host GPU. This is defined by the manufacturer's +driver. ```yaml Type: UInt64 @@ -156,7 +173,9 @@ Accept wildcard characters: False ``` ### -MaxPartitionEncode -The maximum number of encoders assigned by the host GPU. This is defined by the manufacturer's driver. + +The maximum number of encoders assigned by the host GPU. This is defined by the manufacturer's +driver. ```yaml Type: UInt64 @@ -171,6 +190,7 @@ Accept wildcard characters: False ``` ### -MaxPartitionVRAM + The maximum VRAM in bytes supported by the host GPU. This is defined by the manufacturer's driver. ```yaml @@ -186,7 +206,9 @@ Accept wildcard characters: False ``` ### -MinPartitionCompute -The minimum number of compute assigned by the host GPU. This is defined by the manufacturer's driver. + +The minimum number of compute assigned by the host GPU. This is defined by the manufacturer's +driver. ```yaml Type: UInt64 @@ -201,7 +223,9 @@ Accept wildcard characters: False ``` ### -MinPartitionDecode -The minimum number of decoders assigned by the host GPU. This is defined by the manufacturer's driver. + +The minimum number of decoders assigned by the host GPU. This is defined by the manufacturer's +driver. ```yaml Type: UInt64 @@ -216,7 +240,9 @@ Accept wildcard characters: False ``` ### -MinPartitionEncode -The minimum number of encoders assigned by the host GPU. This is defined by the manufacturer's driver. + +The minimum number of encoders assigned by the host GPU. This is defined by the manufacturer's +driver. ```yaml Type: UInt64 @@ -231,6 +257,7 @@ Accept wildcard characters: False ``` ### -MinPartitionVRAM + The minimum VRAM in bytes supported by the host GPU. This is defined by the manufacturer's driver. ```yaml @@ -246,7 +273,9 @@ Accept wildcard characters: False ``` ### -OptimalPartitionCompute -The optimal number of compute assigned by the host GPU. This is defined by the manufacturer's driver. + +The optimal number of compute assigned by the host GPU. This is defined by the manufacturer's +driver. ```yaml Type: UInt64 @@ -261,7 +290,9 @@ Accept wildcard characters: False ``` ### -OptimalPartitionDecode -The optimal number of decoders assigned by the host GPU. This is defined by the manufacturer's driver. + +The optimal number of decoders assigned by the host GPU. This is defined by the manufacturer's +driver. ```yaml Type: UInt64 @@ -276,7 +307,9 @@ Accept wildcard characters: False ``` ### -OptimalPartitionEncode -The optimal number of encoders assigned by the host GPU. This is defined by the manufacturer's driver. + +The optimal number of encoders assigned by the host GPU. This is defined by the manufacturer's +driver. ```yaml Type: UInt64 @@ -291,6 +324,7 @@ Accept wildcard characters: False ``` ### -OptimalPartitionVRAM + The optimal VRAM in bytes supported by the host GPU. This is defined by the manufacturer's driver. ```yaml @@ -306,6 +340,7 @@ Accept wildcard characters: False ``` ### -Passthru + Returns an object for each process that the cmdlet started. ```yaml @@ -321,6 +356,7 @@ Accept wildcard characters: False ``` ### -VM + Specifies the virtual machine whose virtual network adapters are to be retrieved. The asterisk (`*`) is the wildcard. If it is specified the cmdlet returns virtual network adapters from every virtual machine in the system. @@ -338,7 +374,8 @@ Accept wildcard characters: False ``` ### -VMGpuPartitionAdapter -GPU partition object obtained from 'Get-VMGpuPartitionAdapter'. + +GPU partition object obtained from `Get-VMGpuPartitionAdapter`. ```yaml Type: VMGpuPartitionAdapter[] @@ -353,7 +390,8 @@ Accept wildcard characters: False ``` ### -VMName -Specifies the name of the virtual machine whose network adapters are to be retrieved. + +Specifies the name of the virtual machine whose network adapters are to be configured. ```yaml Type: String[] @@ -368,6 +406,7 @@ Accept wildcard characters: False ``` ### -Confirm + Prompts you for confirmation before running the cmdlet. ```yaml @@ -383,8 +422,8 @@ Accept wildcard characters: False ``` ### -WhatIf -Shows what would happen if the cmdlet runs. -The cmdlet is not run. + +Shows what would happen if the cmdlet runs. The cmdlet is not run. ```yaml Type: SwitchParameter @@ -399,7 +438,11 @@ Accept wildcard characters: False ``` ### CommonParameters -This cmdlet supports the common parameters: -Debug, -ErrorAction, -ErrorVariable, -InformationAction, -InformationVariable, -OutVariable, -OutBuffer, -PipelineVariable, -Verbose, -WarningAction, and -WarningVariable. For more information, see [about_CommonParameters](https://go.microsoft.com/fwlink/?LinkID=113216). + +This cmdlet supports the common parameters: -Debug, -ErrorAction, -ErrorVariable, +-InformationAction, -InformationVariable, -OutVariable, -OutBuffer, -PipelineVariable, -Verbose, +-WarningAction, and -WarningVariable. For more information, see +[about_CommonParameters](/powershell/module/microsoft.powershell.core/about/about_commonparameters). ## INPUTS @@ -416,3 +459,9 @@ This cmdlet supports the common parameters: -Debug, -ErrorAction, -ErrorVariable ## NOTES ## RELATED LINKS + +[Add-VMGpuPartitionAdapter](add-vmgpupartitionadapter.md) + +[Get-VMGpuPartitionAdapter](get-vmgpupartitionadapter.md) + +[Remove-VMGpuPartitionAdapter](remove-vmgpupartitionadapter.md) diff --git a/docset/winserver2025-ps/hyper-v/Set-VMHostPartitionableGpu.md b/docset/winserver2025-ps/hyper-v/Set-VMHostPartitionableGpu.md index a6ef57aec9..cd2af1a11a 100644 --- a/docset/winserver2025-ps/hyper-v/Set-VMHostPartitionableGpu.md +++ b/docset/winserver2025-ps/hyper-v/Set-VMHostPartitionableGpu.md @@ -2,7 +2,7 @@ description: Configures the host partitionable GPU to the number of partitions supported by the manufacturer. external help file: Microsoft.HyperV.PowerShell.Cmdlets.dll-Help.xml Module Name: Hyper-V -ms.date: 10/21/2022 +ms.date: 06/12/2024 online version: https://learn.microsoft.com/powershell/module/hyper-v/set-vmhostpartitionablegpu?view=windowsserver2025-ps&wt.mc_id=ps-gethelp schema: 2.0.0 title: Set-VMHostPartitionableGpu @@ -16,44 +16,53 @@ Configures the host partitionable GPU to the number of partitions supported by t ## SYNTAX ### ComputerName (Default) + ``` Set-VMHostPartitionableGpu [[-ComputerName] ] [[-Credential] ] [-Passthru] [-PartitionCount ] [] ``` ### CimSession + ``` Set-VMHostPartitionableGpu [-CimSession] [-Passthru] [-PartitionCount ] [] ``` ### Object + ``` Set-VMHostPartitionableGpu [-HostPartitionableGpu] [-Passthru] [-PartitionCount ] [] ``` ### Name + ``` -Set-VMHostPartitionableGpu [-Passthru] [-Name ] [-PartitionCount ] [] +Set-VMHostPartitionableGpu [-Passthru] [-Name ] [-PartitionCount ] + [] ``` ## DESCRIPTION -The `Set-VMHostPartitionableGpu` cmdlet configures the host partitionable GPU to the number of partitions supported by the manufacturer. + +The `Set-VMHostPartitionableGpu` cmdlet configures the host partitionable GPU to the number of +partitions supported by the manufacturer. ## EXAMPLES ### Example 1 + ```powershell -Set-VMHostPartitionableGpu -ComputerName SampleHost -partitioncount 8 +Set-VMHostPartitionableGpu -ComputerName "MyHost" -PartitionCount 8 ``` This example partitions a GPU in a specific host into eight partitions. ### Example 2 + ```powershell -$GPU = Get-VMHostPartitionableGpu -name "SampleGPUDeviceIDName" -Set-VMHostPartitionableGpu -Name $GPU -partitionCount 4 +$GPU = Get-VMHostPartitionableGpu -Name "GPUDeviceIDName" +Set-VMHostPartitionableGpu -Name $GPU -PartitionCount 4 ``` This example partitions a GPU in a host into four partitions by using the GPU device ID name. @@ -61,8 +70,11 @@ This example partitions a GPU in a host into four partitions by using the GPU de ## PARAMETERS ### -CimSession -Runs the cmdlet in a remote session or on a remote computer. Enter a computer name or a session object, such as the output of a [New-CimSession](https://go.microsoft.com/fwlink/p/?LinkId=227967) or [Get-CimSession](https://go.microsoft.com/fwlink/p/?LinkId=227966) cmdlet. -The default is the current session on the local computer. + +Runs the cmdlet in a remote session or on a remote computer. Enter a computer name or a session +object, such as the output of a [New-CimSession](/powershell/module/cimcmdlets/new-cimsession) +or [Get-CimSession](/powershell/module/cimcmdlets/get-cimsession) cmdlet. The default is the +current session on the local computer. ```yaml Type: CimSession[] @@ -77,9 +89,10 @@ Accept wildcard characters: False ``` ### -ComputerName -Specifies one or more Hyper-V hosts on the virtual network adapters are to be retrieved. NetBIOS names, IP addresses, and fully qualified domain names are allowed. -The default is the local computer. -Use localhost or a dot ('.') to specify the local computer explicitly. + +Specifies one or more Hyper-V hosts on the virtual network adapters are to be retrieved. NetBIOS +names, IP addresses, and fully qualified domain names are allowed. The default is the local +computer. Use localhost or a dot (`.`) to specify the local computer explicitly. ```yaml Type: String[] @@ -94,8 +107,9 @@ Accept wildcard characters: False ``` ### -Credential -Specifies one or more user accounts that have permission to perform this action. -The default is the current user. + +Specifies one or more user accounts that have permission to perform this action. The default is the +current user. ```yaml Type: PSCredential[] @@ -110,7 +124,8 @@ Accept wildcard characters: False ``` ### -HostPartitionableGpu -Full GPU object, obtained by executing 'Get-VMHostPartitionableGpu'. + +Full GPU object, obtained by executing `Get-VMHostPartitionableGpu`. ```yaml Type: VMHostPartitionableGpu[] @@ -125,6 +140,7 @@ Accept wildcard characters: False ``` ### -Name + Specifies the name of the GPU. ```yaml @@ -140,7 +156,9 @@ Accept wildcard characters: False ``` ### -PartitionCount -Specifies the number of partitions that the GPU will assign. The number of partitions is defined by the manufacturer. + +Specifies the number of partitions that the GPU will assign. The number of partitions is defined by +the manufacturer. ```yaml Type: UInt16 @@ -155,6 +173,7 @@ Accept wildcard characters: False ``` ### -Passthru + Returns an object for each process that the cmdlet started. ```yaml @@ -170,7 +189,11 @@ Accept wildcard characters: False ``` ### CommonParameters -This cmdlet supports the common parameters: -Debug, -ErrorAction, -ErrorVariable, -InformationAction, -InformationVariable, -OutVariable, -OutBuffer, -PipelineVariable, -Verbose, -WarningAction, and -WarningVariable. For more information, see [about_CommonParameters](https://go.microsoft.com/fwlink/?LinkID=113216). + +This cmdlet supports the common parameters: -Debug, -ErrorAction, -ErrorVariable, +-InformationAction, -InformationVariable, -OutVariable, -OutBuffer, -PipelineVariable, -Verbose, +-WarningAction, and -WarningVariable. For more information, see +[about_CommonParameters](/powershell/module/microsoft.powershell.core/about/about_commonparameters). ## INPUTS @@ -185,3 +208,5 @@ This cmdlet supports the common parameters: -Debug, -ErrorAction, -ErrorVariable ## NOTES ## RELATED LINKS + +[Get-VMHostPartitionableGpu](get-vmhostpartitionablegpu.md) diff --git a/docset/winserver2025-ps/smbshare/Get-SmbServerCertificateMapping.md b/docset/winserver2025-ps/smbshare/Get-SmbServerCertificateMapping.md index fe61b1bcbe..cf7db1e2a0 100644 --- a/docset/winserver2025-ps/smbshare/Get-SmbServerCertificateMapping.md +++ b/docset/winserver2025-ps/smbshare/Get-SmbServerCertificateMapping.md @@ -28,6 +28,16 @@ Get-SmbServerCertificateMapping [[-Name] ] [[-Subject] ] The `Get-SmbServerCertificateMapping` cmdlet retrieves the certificates associated with the SMB server for SMB over QUIC. For more information, see [SMB over QUIC](https://aka.ms/smboverquic). +> [!NOTE] +> +> - If the **RequireClientAuthentication** parameter is set to `$true` and +> **SkipClientCertificateAccessCheck** is set to `$false`, the server will perform both client +> certificate validation and access control checks. +> +> - If the **RequireClientAuthentication** parameter is set to `$true` and +> **SkipClientCertificateAccessCheck** is also set to `$true`, the server will perform client +> certificate validation but no access control checks. + ## EXAMPLES ### Example 1 - Retrieve the certificate mapped to two SMB over QUIC server names @@ -177,13 +187,15 @@ Accept wildcard characters: False ### -SkipClientCertificateAccessCheck Specifies whether the server should skip the check for client certificate access when a client -connects. When this parameter is set to `$true`, the server will not check whether the client has -access to the certificate it presents. This can be useful in scenarios where the server is acting -as a gateway or proxy, and does not need to perform full certificate validation. +connects. This parameter only applies when the server certificate mapping +**RequireClientAuthentication** value is `$true`. When this parameter is set to `$true`, the server +will not perform the access control checks based on the client certificates. This can be useful in +scenarios where the server is acting as a gateway or proxy and client certificate validation is +sufficient. However, it can also increase the risk of security breaches. When this parameter is set to -`$false`, the server will check whether the client has access to the certificate it presents before -allowing the client to connect. +`$false`, the server will perform the access control checks based on the client certificates in +addition to the client certificate validation before allowing the client to connect. ```yaml Type: Boolean[] diff --git a/docset/winserver2025-ps/smbshare/New-SmbServerCertificateMapping.md b/docset/winserver2025-ps/smbshare/New-SmbServerCertificateMapping.md index b78432d2e1..dc3698caac 100644 --- a/docset/winserver2025-ps/smbshare/New-SmbServerCertificateMapping.md +++ b/docset/winserver2025-ps/smbshare/New-SmbServerCertificateMapping.md @@ -28,6 +28,16 @@ New-SmbServerCertificateMapping [-Name] [-Thumbprint] [-StoreN The `New-SmbServerCertificateMapping` cmdlet associates a certificate to the SMB server for SMB over QUIC. For more information, see [SMB over QUIC](https://aka.ms/smboverquic). +> [!NOTE] +> +> - If the **RequireClientAuthentication** parameter is set to `$true` and +> **SkipClientCertificateAccessCheck** is set to `$false`, the server will perform both client +> certificate validation and access control checks. +> +> - If the **RequireClientAuthentication** parameter is set to `$true` and +> **SkipClientCertificateAccessCheck** is also set to `$true`, the server will perform client +> certificate validation but no access control checks. + ## EXAMPLES ### Example 1 - Map a certificate located in the local machine's personal store @@ -182,13 +192,15 @@ Accept wildcard characters: False ### -SkipClientCertificateAccessCheck Specifies whether the server should skip the check for client certificate access when a client -connects. When this parameter is set to `$true`, the server will not check whether the client has -access to the certificate it presents. This can be useful in scenarios where the server is acting -as a gateway or proxy, and does not need to perform full certificate validation. +connects. This parameter only applies when the server certificate mapping +**RequireClientAuthentication** value is `$true`. When this parameter is set to `$true`, the server +will not perform the access control checks based on the client certificates. This can be useful in +scenarios where the server is acting as a gateway or proxy and client certificate validation is +sufficient. However, it can also increase the risk of security breaches. When this parameter is set to -`$false`, the server will check whether the client has access to the certificate it presents before -allowing the client to connect. +`$false`, the server will perform the access control checks based on the client certificates in +addition to the client certificate validation before allowing the client to connect. ```yaml Type: Boolean diff --git a/docset/winserver2025-ps/smbshare/Remove-SmbServerCertificateMapping.md b/docset/winserver2025-ps/smbshare/Remove-SmbServerCertificateMapping.md index e0883ed395..bb26433f39 100644 --- a/docset/winserver2025-ps/smbshare/Remove-SmbServerCertificateMapping.md +++ b/docset/winserver2025-ps/smbshare/Remove-SmbServerCertificateMapping.md @@ -40,6 +40,16 @@ The `Remove-SmbServerCertificateMapping` cmdlet removes the certificates associa server for SMB over QUIC. For more information, review [SMB over QUIC](/windows-server/storage/file-server/smb-over-quic). +> [!NOTE] +> +> - If the **RequireClientAuthentication** parameter is set to `$true` and +> **SkipClientCertificateAccessCheck** is set to `$false`, the server will perform both client +> certificate validation and access control checks. +> +> - If the **RequireClientAuthentication** parameter is set to `$true` and +> **SkipClientCertificateAccessCheck** is also set to `$true`, the server will perform client +> certificate validation but no access control checks. + ## EXAMPLES ### Example 1 - Remove a certificate mapping for SMB server edge endpoint @@ -242,13 +252,15 @@ Accept wildcard characters: False ### -SkipClientCertificateAccessCheck Specifies whether the server should skip the check for client certificate access when a client -connects. When this parameter is set to `$true`, the server will not check whether the client has -access to the certificate it presents. This can be useful in scenarios where the server is acting -as a gateway or proxy, and does not need to perform full certificate validation. +connects. This parameter only applies when the server certificate mapping +**RequireClientAuthentication** value is `$true`. When this parameter is set to `$true`, the server +will not perform the access control checks based on the client certificates. This can be useful in +scenarios where the server is acting as a gateway or proxy and client certificate validation is +sufficient. However, it can also increase the risk of security breaches. When this parameter is set to -`$false`, the server will check whether the client has access to the certificate it presents before -allowing the client to connect. +`$false`, the server will perform the access control checks based on the client certificates in +addition to the client certificate validation before allowing the client to connect. ```yaml Type: Boolean[] diff --git a/docset/winserver2025-ps/smbshare/Set-SmbServerCertificateMapping.md b/docset/winserver2025-ps/smbshare/Set-SmbServerCertificateMapping.md index a30edda1ef..341c81209f 100644 --- a/docset/winserver2025-ps/smbshare/Set-SmbServerCertificateMapping.md +++ b/docset/winserver2025-ps/smbshare/Set-SmbServerCertificateMapping.md @@ -38,6 +38,16 @@ Set-SmbServerCertificateMapping -InputObject [-Flags ] [- The `Set-SmbServerCertificateMapping` cmdlet modifies a certificate's association to the SMB server for SMB over QUIC. For more information, see [SMB over QUIC](https://aka.ms/smboverquic). +> [!NOTE] +> +> - If the **RequireClientAuthentication** parameter is set to `$true` and +> **SkipClientCertificateAccessCheck** is set to `$false`, the server will perform both client +> certificate validation and access control checks. +> +> - If the **RequireClientAuthentication** parameter is set to `$true` and +> **SkipClientCertificateAccessCheck** is also set to `$true`, the server will perform client +> certificate validation but no access control checks. + ## EXAMPLES ### Example 1: Enable Named Pipes for the SMB over QUIC endpoint @@ -187,13 +197,15 @@ Accept wildcard characters: False ### -SkipClientCertificateAccessCheck Specifies whether the server should skip the check for client certificate access when a client -connects. When this parameter is set to `$true`, the server will not check whether the client has -access to the certificate it presents. This can be useful in scenarios where the server is acting -as a gateway or proxy, and does not need to perform full certificate validation. +connects. This parameter only applies when the server certificate mapping +**RequireClientAuthentication** value is `$true`. When this parameter is set to `$true`, the server +will not perform the access control checks based on the client certificates. This can be useful in +scenarios where the server is acting as a gateway or proxy and client certificate validation is +sufficient. However, it can also increase the risk of security breaches. When this parameter is set to -`$false`, the server will check whether the client has access to the certificate it presents before -allowing the client to connect. +`$false`, the server will perform the access control checks based on the client certificates in +addition to the client certificate validation before allowing the client to connect. ```yaml Type: Boolean diff --git a/docset/winserver2025-ps/startlayout/Import-StartLayout.md b/docset/winserver2025-ps/startlayout/Import-StartLayout.md index e26c8f0d95..47479bd6be 100644 --- a/docset/winserver2025-ps/startlayout/Import-StartLayout.md +++ b/docset/winserver2025-ps/startlayout/Import-StartLayout.md @@ -16,12 +16,12 @@ Imports the layout of the Start into a mounted Windows image. ## SYNTAX ### Path -``` +```powershell Import-StartLayout [-LayoutPath] [-MountPath] [-WhatIf] [-Confirm] [] ``` ### LiteralPath -``` +```powershell Import-StartLayout -LayoutLiteralPath -MountLiteralPath [-WhatIf] [-Confirm] [] ``` @@ -36,6 +36,9 @@ You must have administrator rights to import a layout. In Windows 10, the Export-StartLayout cmdlet exports layouts as .xml files, and the **Import-StartLayout** cmdlet imports only .xml files. +> [!CAUTION] +> The Import-StartLayout cmdlet is deprecated in Windows 11. It has no effect on either Start or Taskbar layout. To configure the Start layout in Windows 11, see [Customize the Windows 11 Start layout](https://learn.microsoft.com/en-us/windows-hardware/customize/desktop/customize-the-windows-11-start-menu). To configure Taskbar layout in Windows 11, see [Customize the Taskbar](https://learn.microsoft.com/en-us/windows-hardware/customize/desktop/customize-the-windows-11-taskbar). + ## EXAMPLES ### Example 1: Import a layout into a Windows image