Edit

Configure and manage SMB Policy Controller (preview) in Windows Server

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.

  1. Open Windows PowerShell as an administrator.

  2. Enable the SMB Policy Controller Feature on Demand (PolicyController) by calling dism.exe directly.

    dism.exe /Online /Enable-Feature /FeatureName:PolicyController
    

    Use dism.exe directly because the DISM PowerShell cmdlets don't enable the SMB Policy Controller Feature on Demand from PowerShell 7.

  3. If DISM requests a restart, restart the device.

  4. If you restarted the device, reopen Windows PowerShell as an administrator.

  5. Verify the module, its commands, and the service.

    Import-Module PolicyController -ErrorAction Stop
    Get-Command -Module PolicyController
    Get-Service -Name PolicyController
    

    Confirm that the module imports, the command list displays the module's commands, and the PolicyController service status is Running. 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.

  1. Check for an existing server-wide intent.

    Get-Intent -System
    

    If 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.

  2. 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-SmbClientConfiguration
    
  3. Create the server-wide Security intent.

    Add-Intent -Security
    

    To create a Performance intent instead, use Add-Intent -Performance. Don't run both commands.

    When Add-Intent completes, SMB Policy Controller (preview) stores the desired intent and started an application attempt. To confirm the effective settings and client access, verify the intent.

  4. 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:

  1. Create and customize the override object.

    $override = New-IntentOverride -Security
    $override.SmbServerConfiguration.RequireSecuritySignature = $true
    
  2. Add the customized server-wide intent.

    Add-Intent -Override $override
    

    Don't combine -Override with -Security or -Performance on Add-Intent. The override object already contains the profile choice.

  3. 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.

  1. 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."
    }
    $intent
    
  2. Review the complete object and then change only the required property. This example requires SMB server signing.

    $intent.SmbServerConfiguration.RequireSecuritySignature = $true
    
  3. Submit the edited object.

    Set-Intent -Override $intent
    

    When Set-Intent completes, SMB Policy Controller (preview) stores the updated intent and starts an application attempt. To confirm the effective settings and client access, verify the intent.

  4. 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.

  1. 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.

  2. 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-SmbClientConfiguration
    
  3. Read 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, IsolatedTransport
    
  4. Compare 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.

  5. 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.

  6. 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.

  1. 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.

  2. Correct the underlying problem reported by SMB Policy Controller.

    • Retry a server-wide intent.

      Set-Intent -Retry
      

      For a share intent, run:

      Set-Intent -ShareName 'Documents' -Retry
      
  3. 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.

  1. Record the service and module state.

    Get-Service -Name PolicyController
    Get-Module -ListAvailable -Name PolicyController
    Get-Command -Module PolicyController
    
  2. Capture the applicable intent object and any errors without changing it.

    Get-Intent -System
    Get-Intent -ShareName 'Documents'
    
  3. 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, IsolatedTransport
    
  4. Record the server time, affected share identity, client identity, operation, and error message. Include any observation time that the intent reports.

  5. Review the SMB client and server event logs for the same period. For log locations and general connectivity checks, see Troubleshoot SMB.

  6. If your support process requires controller-specific tracing, first inspect the tracing help that the installed module supplies.

    Get-Help Set-IntentTracing -Full
    

    Follow 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.

  1. Record the server-wide intent and all relevant effective server settings.

    Get-Intent -System
    Get-SmbServerConfiguration
    Get-SmbClientConfiguration
    
  2. Use 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 Documents with 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, IsolatedTransport
    
  3. Review the installed module help and your change plan before you use broad removal.

    Get-Help Remove-Intent -Full
    
  4. Start the server-wide removal.

    Warning

    Running Remove-Intent without parameters is equivalent to Remove-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 -ShareName for share-only removal.

    Remove-Intent -System
    

    During 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.

  5. 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.

  6. Compare effective settings with the pre-intent records for each affected target, and test representative client access.

  7. If removal doesn't complete, preserve the evidence and correct the reported cause.

  8. After you correct the reported cause, run Remove-Intent -System to retry any incomplete removals. Don't use Set-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.