Create a mapping to an SMB share.
Syntax
New-SmbMapping [[-LocalPath] String] [[-RemotePath] String] [-CimSession CimSession[]]
[-UserName String] [-Password String] [-SaveCredentials] [-Persistent Boolean] [-HomeFolder]
[-AsJob] [-CompressNetworkTraffic Boolean] [-GlobalMapping] [-RequireIntegrity Boolean]
[-RequirePrivacy Boolean] [-ThrottleLimit Int32] [-SkipCertificateCheck]
[-TransportType TransportType] [-UseWriteThrough Boolean]
[-whatIf] [-confirm] [CommonParameters]
Key
-AsJob
Run the cmdlet as a background job.
Use this parameter to run commands that take a long time to complete.
-CompressNetworkTraffic
Request SMB compression for the mapped drive if the SMB server supports it.
This can significantly speed up data transfer speeds on networks with less bandwidth.
-CimSession [CimSession[]]
Run 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 or Get-CimSession cmdlet.
The default is the current session on the local computer.
-GlobalMapping
Make the SMB mapping global instead of user-specific.
This is equivalent to using New-SmbGlobalMapping without any explicit allow or deny settings.
-HomeFolder
Indicates that the connection is made to the home folder of the user.
-LocalPath [String]
The drive letter to map, a single letter followed by a colon: e.g. H:
-Password [String]
A password to be used to connect to the SMB share.
-Persistent [Boolean]
Make this connection available outside PowerShell (e.g. in File Explorer) and persistent when
the user logs out of Windows and logs in again.
-RequireIntegrity
Require SMB signing for the mapped drive.
-RequirePrivacy
Require SMB encryption for the mapped drive.
-RemotePath [String]
The remote path that will be accessed from this computer.
-SaveCredentials
Save the credentials provided to use when another mapping to the same SMB server is created.
-SkipCertificateCheck
Do not require the client to trust the server certificate’s issuer
in order to connect using SMB over QUIC.
-TransportType
The network transport to be used by SMB.
Acceptable values:
TCP: Use TCP network transport.
QUIC: Use QUIC network transport.
None: Use default transport behavior (first try TCP then try QUIC).
-ThrottleLimit [Int32]
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 will calculate 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.
-UserName [String]
The user name to use to connect to the SMB share.
-UseWriteThrough
Require forced unit access (“write through”) and bypass all OS caches, forcing IO to disk.
-whatIf
Describe what would happen if you executed the command without
actually executing the command.
-confirm
Prompt for confirmation before executing the command.
New-SmbMapping creates temporary and persistent drives that are mapped to or associated with a location in a data store, such as a network drive, a directory or the local computer.
Mapped drives added using New-SmbMapping -persistent will be available to other applications such as File Explorer only after they have been closed and reopened. For an immediate connection use New-PSDrive.
Performance: When mapping network drives at login, performance can be important. Of the various methods available, New-SmbMapping is the slowest to make a new connection. If the .Net framework has to be loaded, then just starting a PowerShell process can take 2 to 3 seconds. In an already running PowerShell session, NET USE will still map a drive significantly faster, though with only the basic options available.
An Elevated 'admin' process will not be able to see drives mapped under a limited user token and vice versa. This default behaviour can be reversed by setting EnableLinkedConnections, but few organisations will do that due to the potential security risks. Windows File Explorer runs as a non-elevated session.
Temporary drives exist only in the current PowerShell session and in sessions that you create in the current session. They can have any name that is valid in PowerShell and can be mapped to any local or remote resource. You can use temporary PowerShell drives to access data in the associated data store, just as you would do with any mapped network drive. You can change locations into the drive, by using Set-Location, and access the contents of the drive by using Get-Item or Get-ChildItem.
Because temporary drives are known only to PowerShell, you can’t access them by using File Explorer, Windows Management Instrumentation (WMI), Component Object Model (COM), Microsoft .NET Framework, or with tools such as NET USE.
To create a non-persistent drive mapping, that will be available to other processes like File Explorer, use New-PSDrive or NET USE.
When the value of the -RemotePath parameter is a UNC path, such as \\Server\Share, the credential specified in the value of the Credential parameter is used to create the Drive. Otherwise, Credential isn’t effective when you're creating new file system drives.
In Q4471218 Mapped network drives are displayed as Unavailable [Red-X] when you run the NET USE command.
Microsoft’s recommendation is to remap them with New-SmbMapping -persistent
If a drive map already exists (e.g. H: ) that must be removed before a new mapping created with New-SmbMapping will succeed. This applies to drives mapped with any of: NET USE / VBScript / New-SmbMapping / New-PSDrive
Requires PowerShell 5.0+ and Windows 10+.
Version Available in Windows version: Support SMB 1 Windows 2000 and WIndows XP
(Deprecated)Samba 1.x
Windows 10 (1909) removes support for SMB 1.0SMB 2 Windows Server 2008 and Windows Vista SP1 Samba 3.6 SMB 2.1 Windows Server 2008 R2 and Windows 7 Samba 4.0.0 SMB 3.0 Windows Server 2012 / 2012 R2
Windows 8Samba 4.2 SMB 3.02 Windows 8.1 / Windows 2012 R2 partial see wiki SMB 3.11 Windows 10 / Windows 2016
Create an SMB mapping:
PS C:\> New-SmbMapping -LocalPath 'X:' -RemotePath '\\Server64\Germany' -persistent $True Status Local Path Remote Path ------ ---------- ----------- OK X: \\Server64\Germany
Create an SMB mapping with compression enabled:
PS C:\> New-SmbMapping -LocalPath "S:" -RemotePath "\\fs1.ss64.com\sales" -CompressNetworkTraffic $true
Create an SMB mapping with a try/catch to report any error:
try {
New-SmbMapping -LocalPath 'X:' -RemotePath '\\Server64\Germany' -Persistent $True
} catch {
Write-Host "There was an error mapping X: to \\Server64\Germany"
}
“Eventually everything connects - people, ideas, objects... the quality of the connections is the key to quality per se” ~ Charles Eames attr.
New-PSDrive - Create a mapped network drive (Windows 7).
Get-SmbMapping - Get Mapped SMB drives.
New-SmbGlobalMapping - Create an SMB global map for all users, primarily used for Windows Containers.
Get-SmbConnection - Retrieve the connections established from the SMB client to any SMB servers.
Remove-SmbMapping - Remove an SMB Mapping.
Windows cmd command: NET USE - Map drive.