The basics of SMB PowerShell, a feature of Windows Server 2012 and SMB 3.0

  • [アーティクル]

1. Overview

1.1. Introduction

Windows Server 2012 provides Windows PowerShell cmdlets and WMI objects to manage SMB File Servers and SMB File Shares.

These new tools are aimed at both System Administrator and Developers.

1.2. Benefits

SMB PowerShell cmdlets allow an IT Administrator to

  • Use the PowerShell command line to manage and monitor File Servers and File Shares.
  • Write scripts that automate common File Server administrative tasks, providing consistent automation.
  • Leverage existing PowerShell skills.
  • Integrate with related PowerShell-managed components (network, block storage, cluster).

WMI objects allow a Developer to

  • Use a simpler API to manage and monitor File Servers and File Shares
  • Leverage existing skills to use WMI classes for management
  • Integrate with related WMI-managed components (network, block storage, cluster).
  • Allow for consistent automation of file-server related processes and policies, including change control.

These cmdlets and objects were designed with the following goals in mind:

  • Administrator-friendly: Consistent set of cmdlets which supersedes the existing NET.EXE tool.
  • Scripting-friendly: Integrates with other PowerShell-managed components.
  • Cluster-aware: Manage both standalone and clustered file servers.
  • Developer-friendly: Enable developers, superseding the related Win32 Net APIs.
  • GUI-friendly: Predictable response time, to allow use by a GUI like Server Manager.
  • Remotable: Able to manage a remote File Server by specifying its name.
  • Properties-aware: Allows getting and setting SMB share properties.
  • Settings-aware: Allows getting and setting SMB server and SMB client configuration settings.
  • Network Interface-aware: Expose information on the network interfaces used the SMB Client and Server, as well as their interactions with SMB Multichannel.

1.3. Requirements

You do not need to install any roles or features in order use the SMB PowerShell and WMI objects in Windows Server 2012.

Certain parameters and settings might be restricted to specific configurations, like the ones related to File Server clusters.

1.4. Supported Configurations

SMB PowerShell and WMI objects are supported in all configurations in Windows Server 2012.

Certain parameters and settings might be restricted to specific configurations, like the ones related to File Server clusters.

2. Configuration

2.1. Installing

The SMB PowerShell cmdlets and WMI objects are available by default in Windows Server 2012.

There is no need to install components, roles, role services or features.

The SMB cmdlets are packaged into two modules called SmbShare and SmbWitness.

These modules are automatically loaded whenever you refer to any of the cmdlets included. No upfront configuration is required.

Optionally, you can load these modules manually using the following PowerShell cmdlet:

Import-Module Smb*

2.2. Enumerating cmdlets

You can list all cmdlets in the SMB PowerShell modules using the Get-Command cmdlets.

For instance, to get a list of cmdlets in the SMB modules sorted by Noun and Verb, use the following cmdlets:

Get-Command –Module Smb* | Sort Noun, Verb

Here’s the list of SMB-related objects (nouns) and methods (verbs) available in Windows Server 2012 Beta:

  • SMB Share: Get, New, Set, Remove
  • SMB Share Access: Get, Grant, Revoke, Block, Unblock
  • SMB Configuration: Get, Set for Server, Client
  • SMB Session: Get, Close
  • SMB Open File: Get, Close
  • SMB Mapping: Get, New, Remove
  • SMB Connection: Get
  • SMB Network Interface: Get for Server, Client
  • SMB Multichannel Connection: Get, Update
  • SMB Multichannel Connection: New, Get, Remove
  • SMB Witness Client: Get, Move

2.3. Getting help for a cmdlet

You can obtain information about any PowerShell cmdlet (including a list of parameters) by using the Get-Help cmdlet. For example, to get help for the Get-SmbShare cmdlet, use the following PowerShell cmdlet:

Get-Help Get-SmbShare

2.4. Uninstalling

The SMB PowerShell cmdlets and WMI objects are available by default in Windows Server 2012. There is no need to uninstall components, roles, role services or features.

3. SMB PowerShell cmdlets

Here are the SMB PowerShell cmdlets, grouped by area, each with a simple description and a sample command line.

3.1. SMB Shares

These cmdlets let you manage SMB shares, including creating new ones, setting their properties and removing them.

Get a list of existing file shares

Get-SmbShare
Get-SmbShare FS*

Create new file share

New-SmbShare –Name ShareName –Path C:LocalFolder

Change the configuration of an existing file share

Set-SmbShare –Name ShareName –Description “This is a test share”

Remove a file share

Remove-SmbShare –Name ShareName

3.2. SMB Share Access

These cmdlets let you manage permissions (access control lists) for SMB shares. You can grant and revoke permissions (full, change or read) to specific accounts, as well as block and unblock access by a specific account.

Get a list of permissions for a file share

Get-SmbShareAccess –Name ShareName

Add permissions for a user, computer or group when creating the file share

New-SmbShare –Name ShareName –Path C:LocalFolder –FullAccess Username

Grant permissions for a user, computer or group after the file share is already created

Grant-SmbShareAccess –Name Share –AccountName User –AccessRight Full

Revoke permissions for a user, computer or group

Revoke-SmbShareAccess –Name ShareName –AccountName Username

Block a specific user, computer or group from a file share

Block-SmbShareAccess –Name ShareName –AccountName Username

Unblock a specific user, computer or group from a file share

Unblock-SmbShareAccess –Name ShareName –AccountName Username

Use the share permissions to configure the NTFS permissions on the folder behind the share

(Get-SmbShare -Name ShareName).PresetPathAcl | Set-Acl

3.3. Sessions and Open Files

These cmdlets let you manage currently open sessions and files on an SMB server, including listing and forcibly closing them.

Get a list of SMB Server sessions

Get-SmbSession

Close a specific SMB Server session by session ID (use the ID as listed by Get-SmbSession)

Close-SmbSession -SessionId 4469316125633

Close a specific SMB Server session by computer (use the name as listed by Get-SmbSession)

Close-SmbSession –ClientComputerName \192.168.101.10

Close a specific SMB Server session by user name (use the name as listed by Get-SmbSession)

Close-SmbSession –ClientUserName DomainUsername

Get a list of currently open files in the SMB Server

Get-SmbOpenFile

Get a list of currently open files by a specific user in the SMB Server

Get-SmbOpenFile –ClientUserName DomainUsername

Close a specific SMB open file by file ID (use the ID as listed by Get-SmbOpenFile)

Close-SmbOpenFile –FileID 8885213595225

Close a specific SMB open file by user name (use the name as listed by Get-SmbOpenFile)

Close-SmbOpenFile –ClientUserName DomainUsername

3.4. Client Connections and Mappings 

These cmdlets let you view current connections and manage drive mappings on an SMB client.

View a list of the SMB connections currently used by an SMB client

Get-SmbConnection

View a list of drives mapped by an SMB client

Get-SmbMapping

To map a new driver to a remote file share

New-SmbMapping -LocalPath X: -RemotePath \FileServerShare

To remove an existing mapping

Remove-SmbMapping -LocalPath Y:

3.5. Network interfaces

These cmdlets let you view the network interface configuration used by SMB Multichannel on an SMB client or SMB server. They also manage current SMB Multichannel connections on the SMB client.

List the network interfaces available to the  SMB server, along with its capabilities

Get-SmbServerNetworkInterface

List the network interfaces available to the  SMB client, along with its capabilities

Get-SmbClientNetworkInterface

List the connections currently in use by SMB Multichannel

Get-SmbMultichannelConnection

List the connections currently in use by SMB Multichannel to talk to a specific server (use the name as listed by Get-SmbMultichannelConnection without any parameters)

Get-SmbMultichannelConnection -ServerName ServerName

Force SMB Multichannel to immediately recalculate its policy and react to potential changes in network topology

Update-SmbMultichannelConnection

Force SMB Multichannel to immediately recalculate its policy for a specific server and react to potential changes in network topology (use the name as listed by Get-SmbMultichannelConnection without any parameters)

Update-SmbMultichannelConnection -ServerName ServerName

Create an SMB Multichannel constraint, which restricts the NICs that SMB Multichannel is allowed to use, by interface ID. This is configured per server

New-SmbMultichannelConstraint -ServerName ServerName -InterfaceId 11, 12

Create an SMB Multichannel constraint, which restricts the NICs that SMB Multichannel is allowed to use, by interface ID. This is configured per server

New-SmbMultichannelConstraint -ServerName ServerName -InterfaceAlias RDMA1, RDMA2

List the currently configured SMB Multichannel constraints for all servers

Get-SmbMultichannelConstraint

List the currently configured SMB Multichannel constraints for a specific server

Get-SmbMultichannelConstraint -ServerName ServerName

Remove SMB Multichannel constraints for a given server

Remove-SmbMultichannelConstraint -ServerName ServerName

Remove all configured SMB Multichannel constraints

Get-SmbMultichannelConstraint | Remove-SmbMultichannelConstraint

3.6. Client and Server Configuration

These cmdlets let you view and change configuration parameters for the SMB server and SMB client.

View the current SMB client configuration settings

Get-SmbClientConfiguration

To change an SMB client configuration setting, like SMB Signing

Set-SmbClientConfiguration -RequireSecuritySignature $true

View the current SMB server configuration settings

Get-SmbServerConfiguration

To change an SMB server configuration setting, like SMB Signing

Set-SmbServerConfiguration -RequireSecuritySignature $true

3.7. Witness

These cmdlets let you view the SMB Witness connections in an SMB Scale-Out configuration. You can also move clients to a different server in the cluster.

Lists the SMB Witness clients currently connecting to the SMB Server

Get-SmbWitnessClient

Move an SMB client in a Scale-Out File Server to another File Server cluster node

Move-SmbWitnessClient -ClientName ClientX -DestinationNode ServerY

4. Troubleshooting

Here are troubleshooting tips for SMB PowerShell.

4.1. Access is denied

Many SMB PowerShell cmdlets require administrator permissions.

Make sure you are logged on as a user with Administrative permissions.

Also make sure you’re running an elevated PowerShell prompt (use the option to “Run as Administrator” when launching PowerShell).

4.2. Cmdlet help is brief and offers no details

During the beta phase, there is limited cmdlet help. While at least a list of parameters is provided, other details may be missing.

Updated help information will be published to the Internet.

You can update the help text for your SMB PowerShell cmdlets using the following PowerShell cmdlet:

Update-Help Smb*

4.3. Failed to Update Help

During the beta phase, it’s possible you get an error saying “Failed to update Help for the module” while running the Update-Help cmdlets.

Here are a few common reasons:

  • You’re having problems with your Internet connection. Verify your Internet connection and try again.
  • The help for the module is not yet available on the Internet. The help will become available by the time Windows Server 2012 is finalized.

4.4. Running cmdlets against a remote file server

SMB PowerShell supports running cmdlets against a remote file server.

You simply have to add the parameter CimSession to your cmdlet.

For instance, to remove the Share1 SMB share on server “FS1” from another server, use the following cmdlet:

Remove-SmbShare –CimSession FS1 –Name Share1

5. Comparing with older technologies

5.1. SMB PowerShell and the NET.EXE tool

For IT Administrators, the new SMB PowerShell supersedes the older NET.EXE tools for all share-related operations.

Here’s a table that compares the old NET.EXE command lines with the new PowerShell cmdlets:

NET.EXE command Equivalent SMB PowerShell
NET SHARE Get-SmbShare New-SmbShare Set-SmbShare Remove-SmbShare
NET FILE Get-SmbOpenFile Close-SmbOpenFile
NET SESSION Get-SmbSession Close-SmbSession
NET USE Get-SmbMapping New-SmbMapping Remove-SmbMapping
NET CONFIG Get-SmbServerConfiguration Set-SmbServerConfiguration Get-SmbClientConfiguration Set-SmbClientConfiguration

5.2. SMB WMI classes and the older NET APIs

For Developers, the new SMB WMI supersedes the older Win32 NET API.

Here’s a table that compares the old NET API and the SMB WMI classes:

Net API call SMB PowerShell
NetShareEnum NetShareGetInfo Get-SmbShare
NetShareSetInfo Set-SmbShare
NetShareAdd New-SmbShare
NetShareDel NetShareDelEx Remove-SmbShare
NetFileEnum NetFileGetInfo Get-SmbOpenFile
NetFileClose Close-SmbOpenFile
NetSessionEnum NetSessionGetInfo Get-SmbSession
NetSessionDel Close-SmbSession

6. Additional SMB PowerShell samples

You can find additional examples of SMB PowerShell cmdlets in the following blog posts:

7. Conclusion

I hope this blog post has helped you understand the basics of SMB PowerShell. I would encourage you to try the new cmdlets with the Windows 8 Consumer Preview and the Windows Server 2012 Beta.

For additional information on the Windows Server 2012 File Server, SMB 3.0 and SMB PowerShell, see the links at Updated Links on Windows Server 2012 File Server and SMB 3.0.

 

 

Update on 06/27: Included new cmdlets in Windows Server 2012 RC

Update on 08/30: Added links to two step-by-step posts and the blog about SMB PowerShell aliases

Comments

  • Anonymous
    April 20, 2016
    Awesome post!I am using PowerShell to determine what version of SMB is in play on my Windows 2012 server, but no data is returned when I submit "Get -SmbConnection". Any thoughts on what I may be doing wrong?
    • Anonymous
      April 22, 2016
      The comment has been removed
  • Anonymous
    February 05, 2017
    A most useful blog post. From what I can tell, the details here are correct for Server 2016 RTM.
  • Anonymous
    May 19, 2017
    How can I use the gsmbsc command to a list of servers to determine if smbv1 is enabled?
  • Anonymous
    October 27, 2017
    Very helpful