Creates a new set of file transfer filter settings. File transfer filter settings are used to block a user’s ability to transfer certain types of files (e.g., files with a .vbs or .ps1 file extension) using a Microsoft Communications Server 2010 client.
Syntax
New-CsFileTransferFilterConfiguration -Identity <XdsIdentity> [-Action <BlockAll | Block>] [-Confirm [<SwitchParameter>]] [-Enabled <$true | $false>] [-Extensions <PSListModifier>] [-Force <SwitchParameter>] [-InMemory <SwitchParameter>] [-WhatIf [<SwitchParameter>]] |
Parameters
Parameter | Required | Type | Description |
---|---|---|---|
Identity |
Required |
XdsIdentity |
Unique identifier to be given to the collection of file transfer settings. The Identity for the new collection is simply the prefix "site:" followed by the site name. For example, to create a new collection of settings for the Redmond site you would use this syntax: -Identity site:Redmond. |
Action |
Optional |
String |
Determines the action to be taken if this collection of file transfer filter settings is enabled. If set to BlockAll then all file transfers will be prohibited, regardless of file extension. If set to Block (the default value) file transfers will be allowed unless the file extension appears as one of the prohibited file types listed in the Extensions property. By default, this means that users will be allowed to transfer .docx files, but not allowed to transfer .exe files. To allow unrestricted file transfers (that is, to allow users to exchange any type of file, regardless of file extension) set the Enabled property of this policy to False. |
Enabled |
Optional |
Boolean |
Enables or disables file transfer filtering. If this parameter is set to True, files with the specified extensions (or all files, depending on the value of the Action property) cannot be transferred using a Communications Server client. If this parameter is set to False, any file can be transferred. The default value is True. |
Extensions |
Optional |
PSListModifier |
List of file extensions that will be blocked. If you attempt to use a Communications Server client to transfer a file that has a file extension matching one of the extensions in this list that transfer will be blocked and the file will not be transferred. This list is ignored if Action is set to BlockAll (all file transfers are blocked) or if Enabled is set to False (no file transfers are blocked). By default, the following file extensions are included in the Extensions property: .ade, .adp, .app, .asp, .bas, .bat, .cer, .chm, .cmd, .com, .cpl, .crt, .csh, .exe, .fxp, .grp, .hlp, .hta, .inf, .ins, .isp, .its, .js, .jse, .ksh, .lnk, .mad, .maf, .mag, .mam, .maq, .mar., mas., .mat, .mau, .mav, .maw, .mda, .mdb. .mde, .mdt, .mdw, .mdz, .msc, .msi, .msp, .mst, .ocx, .ops, .pcd, .pif, .pl, .pnp, .prf, .prg, .pst, .reg, .scf, .scr, .sct, .shb, .shs, .tmp, .url, .vb, .vbe, .vbs, .vsd, .vsmacros, .vss, .vst, .vsw, .ws, .wsc. .wsf, .wsh |
InMemory |
Optional |
Switch Parameter |
Creates an object reference without actually committing the object as a permanent change. If you assign the output of this cmdlet called with this parameter to a variable, you can make changes to the properties of the object reference and then commit those changes by calling this cmdlet’s matching Set- cmdlet. |
Confirm |
Optional |
Switch Parameter |
Prompts you for confirmation before executing the command. |
Force |
Optional |
SwitchParameter |
Suppresses any confirmation prompts that would otherwise be displayed before making changes. |
WhatIf |
Optional |
Switch Parameter |
Describes what would happen if you executed the command without actually executing the command. |
Detailed Description
When sending instant messages, users can attach and send files to the other participants in the conversation. Communications Server 2010 can be configured so that files with certain extensions - typically extensions of file types that could potentially prove harmful - are not allowed to be sent from a Communications Server client.
When you install Communications Server a single collection of file transfer filter settings - configured at the global scope - is created for you. By default, those global settings apply to all the users in your organization. Alternatively, you can use the New-CsFileTransferFilterConfiguration cmdlet to create custom collections of file transfer settings for individual sites. If a custom collection exists for a given site then those file transfer settings will be applied to all the users in that site. If no such collection exists for a site then the global settings will be applied instead.
Note that you cannot create new file transfer settings at the global scope; however, you can use the Set-CsFileTransferFilterConfiguration cmdlet to modify the global settings. Likewise, you cannot create a new collection of settings for a site that already has such a collection; if you try that, your command will fail.
Return Types
New-CsFileTransferFilterConfiguration creates new instances of the Microsoft.Rtc.Management.WritableConfig.Settings.ImFilter.FileTransferFilterConfiguration object.
Examples
-------------------------- Example 1 --------------------------
Copy Code | |
---|---|
New-CsFileTransferFilterConfiguration -Identity site:Redmond |
In the preceding command, New-CsFileTransferFilterConfiguration is used to create a new instant message file transfer filter configuration with the Identity site:Redmond. Because no additional parameters were specified, these settings will be created using the default values.
-------------------------- Example 2 --------------------------
Copy Code | |
---|---|
New-CsFileTransferFilterConfiguration -Identity site:Redmond -Extensions @{Add=".ps1"} |
In this command, New-CsFileTransferFilterConfiguration is used to create new file transfer filter settings with the Identity site:Redmond. Because the Extensions parameter has been specified, the new configuration will contain all the default values plus an additional file extension: .ps1. This new extension is added by using the Extensions parameter and the list modifier Add followed by the file extension to be added. (Note that you must include the period as part of the file extension.) To add multiple file extensions simply separate those extensions using commas: @{Add=".ps1",".ps2",".ps3"}
-------------------------- Example 3 --------------------------
Copy Code | |
---|---|
New-CsFileTransferFilterConfiguration -Identity site:Redmond -Extensions @{Replace=".vbs",".ps1"} |
In Example 3, New-CsFileTransferFilterConfiguration is used to create new file transfer filter settings with the Identity site:Redmond. This example is similar to Example 2 except that the Replace list modifier has been used instead of the Add modifier. This means that the complete set of file extensions will be replaced by the two specified file extensions: .vbs and .ps1. In this case the only files blocked at the Redmond site will be .vbs and .ps1.
-------------------------- Example 4 --------------------------
Copy Code | |
---|---|
$x = New-CsFileTransferFilterConfiguration -Identity site:Redmond -InMemory $x.Action = "BlockAll" Set-CsFileTransferFilterConfiguration -Instance $x |
Example 4 demonstrates the use of the -InMemory parameter to create a file transfer filter settings collection that initially resides in memory only. To do this the first command in the example uses New-CsFileTransferFilterConfiguration and the InMemory parameter to create a new collection of file transfer filter settings with the Identity site:Redmond. At this point in time, the new settings exist only in memory; users in the Redmond site will still be governed by the global file transfer filter settings.
In the second command, the value of the Action property for this in-memory instance is set to "BlockAll". Finally, the third command in the example use Set-CsFileTransferFilterConfiguration to create the new collection of settings and apply them to the Redmond site.