Note
Access to this page requires authorization. You can try signing in or changing directories.
Access to this page requires authorization. You can try changing directories.
SMB Policy Controller (preview) stores the Server Message Block (SMB) settings you want for a device or an existing file share and corrects managed settings when they drift. Use it when you need server-wide and share-level configuration to stay aligned with a defined security or performance outcome.
In this article, you use Windows PowerShell to manage server-wide and share-level SMB intents through their lifecycle while verifying that the effective configuration matches your intended outcome.
Important
SMB Policy Controller is currently in PREVIEW. This information relates to a prerelease product that may be substantially modified before it's released. Microsoft makes no warranties, expressed or implied, with respect to the information provided here.
Prerequisites
- Windows Server Insider Preview build 29707 or later.
- An elevated Windows PowerShell session on the device. For instructions, see Start Windows PowerShell with administrative privileges.
- Administrative access to the affected device. A server intent manages the local SMB server configuration, SMB client configuration, managed SMB registry settings, and alternative-port configuration.
- An existing SMB share for the share-intent procedures. SMB Policy Controller (preview) doesn't create the share, its folder, or its permissions.
- Representative clients and user identities for access testing.
- A change plan that identifies affected servers, shares, clients, and other configuration tools that can change the same SMB settings.
- A record of the effective SMB settings before you create an intent. Use this record when you verify that removal returned the managed settings to their pre-intent values.
Install SMB Policy Controller (preview)
On a device that runs Windows Server Insider Preview build 29707 or later, install the SMB Policy Controller (preview) Feature on Demand and verify that it's ready before you configure an intent.
Open Windows PowerShell as an administrator.
Enable the SMB Policy Controller Feature on Demand (
PolicyController) by callingdism.exedirectly.dism.exe /Online /Enable-Feature /FeatureName:PolicyControllerUse
dism.exedirectly because the DISM PowerShell cmdlets don't enable the SMB Policy Controller Feature on Demand from PowerShell 7.If DISM requests a restart, restart the device.
If you restarted the device, reopen Windows PowerShell as an administrator.
Verify the module, its commands, and the service.
Import-Module PolicyController -ErrorAction Stop Get-Command -Module PolicyController Get-Service -Name PolicyControllerConfirm that the module imports, the command list displays the module's commands, and the
PolicyControllerservice status isRunning. If installation verification fails, don't continue to intent configuration.
Choose an intent scope
Choose a server-wide intent to manage host-wide SMB server, SMB client, managed SMB registry settings, and alternative-port configuration. Choose a share-level intent to manage one named, existing SMB share. The scopes are separate. When both intents exist, verify their combined effective settings.
For details about scope interactions and other tools that manage the same settings, see Server and share intent.
Choose a profile and workload selector
Choose the Security profile when strengthening SMB protection is the priority. Choose the Performance profile when workload performance is the priority and you accept its security and availability tradeoffs. For a share intent, also choose the User data workload selector for shares that people and teams use interactively or the Application data workload selector for shares that applications use for data. Make these choices before you create the intent. For profile effects, tradeoffs, and workload selector guidance, see SMB Policy Controller (preview) profiles and workload selectors. For override behavior and limitations, see SMB Policy Controller profile-derived overrides.
For a new intent, use an override object when a supported setting must differ from its profile value. For an existing intent, retrieve the current intent, edit only the required properties, and submit the edited object with Set-Intent -Override. This pattern retains settings that you don't intend to change.
Configure an intent
Select the tab for the intent scope that you want to configure.
A server-wide intent manages host-wide SMB server, SMB client, managed SMB registry settings, and alternative-port configuration. Apply it together with one or more share intents when you need both scopes. To configure a server-wide intent, use the following steps.
Check for an existing server-wide intent.
Get-Intent -SystemIf an intent exists, don't add another one. Use the update procedure instead. If the command reports a read or persistence error, resolve the error before continuing.
Review the current effective SMB configuration and confirm that you chose the Security profile when SMB protection is the priority or the Performance profile when workload performance is the priority and you accept its security and availability tradeoffs. For detailed guidance, see SMB Policy Controller (preview) profiles and workload selectors.
Get-SmbServerConfiguration Get-SmbClientConfigurationCreate the server-wide Security intent.
Add-Intent -SecurityTo create a Performance intent instead, use
Add-Intent -Performance. Don't run both commands.When
Add-Intentcompletes, SMB Policy Controller (preview) stores the desired intent and started an application attempt. To confirm the effective settings and client access, verify the intent.Immediately complete the verification procedure.
Add a customized intent
In SMB Policy Controller (preview), select the tab for the intent scope that you want to customize.
For a new server-wide intent, use an override object when a supported setting must differ from the selected built-in profile. The following procedure creates a Security-profile server configuration, requires SMB server signing, and applies the customized object:
Create and customize the override object.
$override = New-IntentOverride -Security $override.SmbServerConfiguration.RequireSecuritySignature = $trueAdd the customized server-wide intent.
Add-Intent -Override $overrideDon't combine
-Overridewith-Securityor-PerformanceonAdd-Intent. The override object already contains the profile choice.Immediately complete the verification procedure.
Update an intent
Use the get, edit, and set pattern to retain settings that you don't intend to change. A new override object uses a profile rather than cloning the existing intent or current live configuration. Select the tab for the intent scope that you want to update.
Read the current server-wide intent.
$intent = Get-Intent -System if ($null -eq $intent) { throw "The server didn't return a readable server-wide intent." } $intentReview the complete object and then change only the required property. This example requires SMB server signing.
$intent.SmbServerConfiguration.RequireSecuritySignature = $trueSubmit the edited object.
Set-Intent -Override $intentWhen
Set-Intentcompletes, SMB Policy Controller (preview) stores the updated intent and starts an application attempt. To confirm the effective settings and client access, verify the intent.Complete the verification procedure.
These examples update selected settings within an existing intent type. They don't establish a profile migration procedure or a procedure for changing between user-data and application-data intent types.
Verify an intent
Use three customer-facing evidence layers: the stored intent, the effective or observed configuration, and representative client success. Check each layer because a saved intent alone doesn't prove that the settings are effective or that clients can use the share. The installed Windows build can present different status details, so don't depend on specific field labels.
Read the applicable stored intent to confirm the saved scope, profile, and settings.
Get-Intent -System Get-Intent -ShareName 'Documents'Run only the command for the scope you're verifying. Inspect the complete returned object and any available status information. Don't interpret a command error as proof that no intent exists.
Read the effective or observed server and client configuration for a server-wide intent. This evidence shows whether the relevant host-wide settings match the stored intent.
Get-SmbServerConfiguration Get-SmbClientConfigurationRead the effective or observed share configuration for a share intent. This evidence shows whether the relevant share settings match the stored intent.
Get-SmbShare -Name 'Documents' -ErrorAction Stop | Format-List Name, ScopeName, Path, Description, FolderEnumerationMode, CachingMode, LeasingMode, CaTimeout, CompressData, ConcurrentUserLimit, ContinuouslyAvailable, DirectoryHandleLeasing, DisableClientMetadataCaching, EncryptData, IsolatedTransportCompare every relevant managed setting with the stored intent and your approved change plan. Check each affected configuration group instead of relying on one summary result.
For a server-wide intent, test representative outbound SMB client operations from the managed device against remote shares that it normally uses. If the managed device hosts shares, also test representative clients' inbound access. For a share intent, test the share from representative clients. Use representative user identities and workload operations, and verify the expected read, write, and denied-access cases that apply.
Record the results and the observation time. Recheck after Group Policy, scripts, clustering operations, or other configuration tools change the same settings.
Retry intent application
The system limits application retries. Retry only after you identify and correct the cause of the failure. Don't automate repeated retries or depend on an assumed retry schedule, attempt count, or counter-reset behavior.
Confirm that the intent is active and that no operation is removing it.
Get-Intent -System Get-Intent -ShareName 'Documents'Run the command for the affected scope.
Correct the underlying problem reported by SMB Policy Controller.
Retry a server-wide intent.
Set-Intent -RetryFor a share intent, run:
Set-Intent -ShareName 'Documents' -Retry
Complete the verification procedure.
Set-Intent -Retry reapplies an active intent. It isn't a profile change, a rollback, or a retry of an incomplete removal. Don't place it in an uncontrolled loop.
Collect diagnostics
Collect stored-intent, effective-state, service, and client evidence from the same time period. This information helps you distinguish controller problems from general SMB connectivity problems.
Record the service and module state.
Get-Service -Name PolicyController Get-Module -ListAvailable -Name PolicyController Get-Command -Module PolicyControllerCapture the applicable intent object and any errors without changing it.
Get-Intent -System Get-Intent -ShareName 'Documents'Capture the effective SMB settings.
Get-SmbServerConfiguration Get-SmbClientConfiguration Get-SmbShare -Name 'Documents' -ErrorAction Stop | Format-List Name, ScopeName, Path, Description, FolderEnumerationMode, CachingMode, LeasingMode, CaTimeout, CompressData, ConcurrentUserLimit, ContinuouslyAvailable, DirectoryHandleLeasing, DisableClientMetadataCaching, EncryptData, IsolatedTransportRecord the server time, affected share identity, client identity, operation, and error message. Include any observation time that the intent reports.
Review the SMB client and server event logs for the same period. For log locations and general connectivity checks, see Troubleshoot SMB.
If your support process requires controller-specific tracing, first inspect the tracing help that the installed module supplies.
Get-Help Set-IntentTracing -FullFollow only the trace procedure, output location, and data-handling requirements in the help for the installed PolicyController module. This article doesn't assume a trace path, provider, file size, or remote-tracing behavior.
Remove an intent and return to previous settings
Select the tab for the intent scope that you want to remove.
When removal succeeds, SMB Policy Controller (preview) returns managed host settings to the values that it captured before it first applied the intent, not to Security or Performance profile defaults. Removing a server-wide intent affects the managed SMB server, SMB client, registry, and alternative-port configuration. Account for every server and share target that broad removal selects before continuing.
Record the server-wide intent and all relevant effective server settings.
Get-Intent -System Get-SmbServerConfiguration Get-SmbClientConfigurationUse your change plan and intent records to account for every persisted or incomplete share-intent lifetime that broad removal can select. For every affected share that still exists, record its stored intent and relevant effective managed settings. Replace
Documentswith the share name, and repeat these commands for every affected existing share. If you can't account for every target and its baseline, don't use broad removal.Get-Intent -ShareName 'Documents' Get-SmbShare -Name 'Documents' -ErrorAction Stop | Format-List Name, ScopeName, Path, Description, FolderEnumerationMode, CachingMode, LeasingMode, CaTimeout, CompressData, ConcurrentUserLimit, ContinuouslyAvailable, DirectoryHandleLeasing, DisableClientMetadataCaching, EncryptData, IsolatedTransportReview the installed module help and your change plan before you use broad removal.
Get-Help Remove-Intent -FullStart the server-wide removal.
Warning
Running
Remove-Intentwithout parameters is equivalent toRemove-Intent -System. It selects the server intent and all persisted or incomplete share-intent lifetimes, and it doesn't prompt for confirmation. The operation can partially complete or fail. In a cluster, resource ownership or offline participating nodes can delay completion or cause it to fail. You must specify-ShareNamefor share-only removal.Remove-Intent -SystemDuring successful processing, SMB Policy Controller returns the managed settings that it captured to their pre-intent values before it finishes removing each intent that the operation selected.
Verify that the removal completed for every target that the operation selected and that SMB Policy Controller returned the managed settings to their pre-intent values. Check the effective configuration instead of assuming that command submission means that the operation completed.
Compare effective settings with the pre-intent records for each affected target, and test representative client access.
If removal doesn't complete, preserve the evidence and correct the reported cause.
After you correct the reported cause, run
Remove-Intent -Systemto retry any incomplete removals. Don't useSet-Intent -Retry, which retries application of an active intent, and don't manually delete controller recovery records.
The removal operation doesn't delete shares or data, and it isn't a backup restore. SMB Policy Controller returns the managed settings that it captured to their pre-intent values.
Troubleshoot common problems
Use the following guidance after collecting diagnostics. Don't delete controller recovery records or apply undocumented repair commands.
| Problem | Recommended action |
|---|---|
| Add reports that an intent already exists | Read the existing intent, then use the get, edit, and set pattern. Don't remove it only to make Add succeed. |
| The system can't find the share | Confirm its exact name, path, and scope with Get-SmbShare. SMB Policy Controller (preview) doesn't create the share. |
| Stored intent and effective settings differ | Check reported application errors, service health, setting applicability, ownership, and other configuration writers. Inspect every managed group because application might be partial. |
| Drift returns after correction | Check for Group Policy, scripts, management tools, or administrators that write the same settings. Coordinate writers instead of repeatedly forcing changes. |
| Client access fails although settings appear compliant | Troubleshoot authentication, authorization, networking, name resolution, dialect negotiation, and the client workload separately. A compliance observation isn't a client-access test. |
| Retry doesn't resolve the problem | Stop retrying, preserve the evidence, and investigate the underlying error. |
| Removal doesn't complete | Preserve the evidence, correct the reported cause, and retry the same Remove-Intent command. |