# File Server Resource Manager on FSx for Windows File Server File Server Resource Manager File Server Resource Manager (FSRM) is a Windows Server feature that helps you manage and classify data stored on your Amazon FSx for Windows File Server file system. FSRM provides automated policy enforcement and reporting capabilities that help you control storage costs, maintain compliance with data management policies, and organize files based on business rules. With FSRM, you can set storage limits to prevent users from consuming excessive storage, automatically identify and classify sensitive data, block unauthorized file types from being saved to business folders, and generate detailed reports about storage usage patterns. These capabilities help you maintain an organized, efficient, and compliant file system without requiring manual intervention for every file or folder. FSRM is particularly valuable for organizations that need to: + Control storage costs by limiting how much disk space users and departments can store + Identify sensitive data such as personally identifiable information or financial records + Enforce policies about which file types are allowed in specific folders + Generate compliance reports about data retention, file ownership, or storage usage + Maintain visibility into how storage is being used across the organization ## Key capabilities Key capabilities + **[Quota Management](fsrm-quota-management.md)** - Set storage limits on folders to control how much space users and applications can consume. You can configure hard quotas that prevent users from exceeding limits or soft quotas that allow overages while sending notifications. Quotas help you manage storage costs and prevent users or departments from consuming disproportionate amounts of storage. + **[File Screening](fsrm-file-screening.md)** - Control which types of files users can save to specific folders. You can block unauthorized file types such as executable files, media files, or personal documents in business folders. File screening helps you enforce data management policies, reduce security risks, and prevent storage waste from non-business files. + **[File Classification](fsrm-file-classification.md)** - Automatically assign metadata properties to files based on their content or location. Classification helps you organize files, identify sensitive data, apply retention policies, and generate reports based on file characteristics. You can classify files by data sensitivity, department, retention period, or any other custom properties you define. + **[Storage Reports](fsrm-storage-reports.md)** - Generate detailed reports about file system usage, including large files, duplicate files, files by owner, files by type, and quota usage. Storage reports help you understand how storage is being consumed, identify files that can be archived or deleted, and make informed decisions about storage management. **Topics** + [ ## Key capabilities ](#managing-files-fsrm-capabilities) + [ # Getting Started with File Server Resource Manager ](enabling-fsrm.md) + [ # Quota Management ](fsrm-quota-management.md) + [ # File Groups ](fsrm-file-groups.md) + [ # File Screening ](fsrm-file-screening.md) + [ # File Classification ](fsrm-file-classification.md) + [ # Storage Reports ](fsrm-storage-reports.md) + [ # File Management Tasks ](fsrm-file-management.md) + [ # FSRM Settings ](fsrm-settings.md) + [ # Event Logs ](fsrm-event-logs.md) + [ # Common Use Cases ](fsrm-common-use-cases.md) # Getting Started with File Server Resource Manager How to Get Started You can enable File Server Resource Manager (FSRM) when creating a new Amazon FSx for Windows File Server file system, or you can update your existing file system to enable FSRM. FSRM is supported only on Amazon FSx for Windows File Server file systems with SSD storage and a throughput capacity of 128 MB/s or greater. You can update the storage type to SSD and modify the throughput capacity at any time after you create the file system. For more information, see [Updating the storage type of a FSx for Windows file system](updating-storage-type.md) and [Managing throughput capacity](managing-throughput-capacity.md). ## To enable FSRM when creating a file system (console) Enable FSRM (console) 1. Open the Amazon FSx console at [https://console.aws.amazon.com/fsx/](https://console.aws.amazon.com/fsx/) 1. On the dashboard, choose **Create file system** to start the file system creation wizard. 1. Choose **Amazon FSx for Windows File Server** and then choose **Next**. 1. Select the **Standard Create** option 1. Provide the required information 1. Open the **File Server Resource Manager** block, choose **Enabled**. 1. For **Event log destination**, choose one of the following options: + **CloudWatch Logs** - Select a CloudWatch Logs log group to receive FSRM event logs. The name of the CloudWatch Logs log group must begin with the `'/aws/fsx/'` prefix. + **Kinesis Data Firehose** - Select a Kinesis Data Firehose delivery stream to receive FSRM event logs 1. Complete the remaining sections and choose **Create file system**. ## To enable FSRM when creating a file system (CLI) Enable FSRM (CLI) To enable FSRM when creating an FSx for Windows File Server file system, use the AWS CLI command `create-file-system`. Include the following FSRM configuration in the `--windows-configuration` parameter: + `FsrmServiceEnabled` - Set to `true` + `EventLogDestination` - The Amazon Resource Name (ARN) that specifies the destination of the FSRM event logs. Can be a CloudWatch Logs log group ARN or Kinesis Data Firehose delivery stream ARN. ``` aws fsx create-file-system \ --file-system-type WINDOWS \ --storage-capacity 300 \ --storage-type SSD \ --subnet-ids subnet-0123456789abcdef0 \ --windows-configuration "ThroughputCapacity=128,WindowsFsrmConfiguration={FsrmServiceEnabled=true,EventLogDestination=arn:aws:logs:us-east-1:123456789012:log-group:/aws/fsx/fsrm}" ``` ## To modify FSRM configuration on an existing file system (console) Modify FSRM (console) 1. Open the Amazon FSx console at [https://console.aws.amazon.com/fsx/](https://console.aws.amazon.com/fsx/). 1. Navigate to **File systems** and choose the Windows file system that you want to modify. 1. Choose the **Administration** tab. 1. In the **File Server Resource Manager** section, choose **Manage**. 1. Make your required changes: + To change the event log destination, select a different CloudWatch Logs log group or Kinesis Data Firehose delivery stream + To enable FSRM, choose **Enabled** + To disable FSRM, choose **Disabled** **Important** Multi-AZ file systems will experience automatic failover and failback events during this process, while Single-AZ file systems will experience a brief period of unavailability. 1. Choose **Save**. You can monitor the update progress on the File systems detail page, in the **Updates** tab. ## To modify FSRM configuration on an existing file system (CLI) Modify FSRM (CLI) To enable and disable FSRM on an existing FSx for Windows File Server file system, use the AWS CLI command `update-file-system`. ### Enabling FSRM Enable FSRM To enable FSRM, include the following FSRM configuration in the `--windows-configuration` parameter: + `FsrmServiceEnabled` - Set to `true` + `EventLogDestination` - The Amazon Resource Name (ARN) that specifies the destination of the FSRM event logs. Can be a CloudWatch Logs log group ARN or Kinesis Data Firehose delivery stream ARN. ``` aws fsx update-file-system \ --file-system-id fs-0123456789abcdef0 \ --windows-configuration FsrmConfiguration='{FsrmServiceEnabled=true,EventLogDestination=”arn:aws:logs:us-east-1:123456789012:log-group:/aws/fsx/fsrm”}' ``` ### Disabling FSRM Disable FSRM To disable FSRM: ``` aws fsx update-file-system \ --file-system-id fs-0123456789abcdef0 \ --windows-configuration FsrmConfiguration='{FsrmServiceEnabled=false}' ``` **Important** Multi-AZ file systems will experience automatic failover and failback events during this process, while Single-AZ file systems will experience a brief period of unavailability. ## FSx remote PowerShell Remote PowerShell To configure and use FSRM features, you must use the Amazon FSx CLI for remote management on PowerShell. For information, see [Starting an Amazon FSx remote PowerShell session](start-remote-powershell-session.md). # Quota Management Quota Management You can use File Server Resource Manager (FSRM) quota management to control the amount of storage space that users consume on your FSx for Windows File Server file system. Quotas help you manage storage capacity by limiting the amount of data that can be stored in specific folders and by generating notifications when storage usage approaches or exceeds defined thresholds. ## How quota management works How it works Quota management provides two types of quotas that you can apply to folders on your file system: Hard quotas Prevent users from saving files after the quota limit is reached. When a user attempts to save a file that would exceed the quota limit, the operation fails and the user receives an error message. Soft quotas Allow users to exceed the quota limit while logging the violation. Soft quotas are useful for monitoring storage usage without enforcing strict limits. ## Quota templates Quota templates Quota templates provide a reusable configuration that defines quota settings, including size limits, quota type (hard or soft), and threshold notifications. After you create a quota template, you can apply it to multiple folders without having to reconfigure the same settings each time. When you update a quota template, you can optionally apply the changes to all quotas that were created from that template. Using quota templates offers several benefits: + **Consistency** - Ensure that similar folders have identical quota configurations + **Efficiency** - Apply quota settings to multiple folders quickly + **Maintainability** - Update quota settings across multiple folders by modifying the template ## Auto apply quotas Auto apply quotas Auto apply quotas automatically create quotas for subfolders based on a specified template. When you create an auto apply quota on a parent folder, FSRM automatically generates a quota for each existing subfolder and for any new subfolders that users create in the future. This approach is useful for scenarios where you want to apply consistent quota limits across multiple user directories or departmental folders. ## Threshold notifications Threshold notifications Thresholds define usage levels at which FSRM takes specific actions. You can configure multiple thresholds for each quota, with each threshold set to a percentage of the quota limit. When storage usage reaches a threshold percentage, FSRM can perform the following actions: Event logging Log an event to Amazon CloudWatch or Amazon Kinesis Data Firehose for monitoring and analysis. You can specify the event severity level (Information, Warning, or Error) and provide a custom message body. Event logging is useful for monitoring quota usage and integrating with existing monitoring systems. Storage reports Generate a storage usage report that provides detailed information about the files and folders consuming storage space. Storage reports help you identify which users or applications are consuming the most storage and make informed decisions about storage management. For more information, see [Storage Reports](fsrm-storage-reports.md). You can configure multiple thresholds with different actions for each quota. For example, you might configure a quota with an Information event at 75 percent usage and a Warning event at 90 percent usage. ## Quota Management commands Management commands You can access three families of FSx remote PowerShell commands for managing Quotas: 1. **Quota commands** - Create, retrieve, modify, remove, and update quotas on specific folders. Use these commands when you need to manage quotas on a folder-by-folder basis. 1. **Quota Template commands** - Create, retrieve, and modify quota templates that define reusable quota configurations. Use these commands to establish standard quota policies that you can apply across multiple folders. 1. **Auto Quota commands** - Create, retrieve, modify, remove, and update auto apply quotas that automatically generate quotas for subfolders. Use these commands when you need to apply consistent quota limits across multiple subfolders without manually creating individual quotas. ### List of Quota Management FSx remote PowerShell commands PowerShell commands list **Note** All the examples in this page assume that you have defined the ` $FSxWindowsRemotePowerShellEndpoint` variable with your file system's Windows Remote PowerShell endpoint. You can find this endpoint in the Amazon FSx console on your file system's details page, or by using the AWS CLI `describe-file-systems` command. ### Quota Commands Quota Commands #### New-FSxFSRMQuota New-FSxFSRMQuota Creates a new quota on a folder. A quota limits the amount of data that users can store in a folder. You can optionally configure the quota to generate notifications when users exceed quota thresholds. **Parameters:** + `Folder (string)` - Required. The folder path where the quota will be applied. + `Size (string)` - Required when not using a Template: The quota size limit. + `Template (string)` - Optional. The name of an existing quota template to use. When you specify a template, you can only use the Description parameter; all other settings are inherited from the template. + `Description (string)` - Optional. A description for the quota. + `SoftLimit (boolean)` - Optional. If set to true, creates a soft quota that allows users to exceed the limit while logging violations. + `Disabled (boolean)` - Optional. If set to true, creates the quota in a disabled state. + `ThresholdConfigurations (array)` - Optional. An array of threshold configurations that specify actions to take at different usage levels. Each configuration has the following properties: + `ThresholdPercentage (number)`: The percentage of the quota limit at which to trigger actions. Enter a value between 0 and 250. + `Action (array)`: One or more actions to take when the threshold is reached. Each action has the following properties: + `ActionType`: The type of action to perform. You can specify the following values: 1. `Event`: Logs an event to the file system's event log. When you specify Event, you must also specify the following properties: + `EventType`: Information, Warning, or Error + `MessageBody`: The message text to log with the event. 1. `Report`: Generates a storage usage report. **Examples:** **1. Create a hard 5GB quota without using a quota template.** ``` Invoke-Command -ComputerName $FSxWindowsRemotePowerShellEndpoint -ConfigurationName FSxRemoteAdmin -ScriptBlock { New-FSxFSRMQuota -Folder "share\test" -Size 5GB } ``` **2. Create soft quota with a threshold notification** ``` $thresholds = [System.Collections.ArrayList]@() $warning = @{ ThresholdPercentage = 75 Action = @( @{ ActionType = "Event" EventType = "Warning" MessageBody = "Quota usage has reached 75%" } ) } $thresholds.Add($warning) Invoke-Command -ComputerName $FSxWindowsRemotePowerShellEndpoint -ConfigurationName FSxRemoteAdmin -ArgumentList ($thresholds) -ScriptBlock { param($thresholds) New-FSxFSRMQuota -Folder "share/test" -Size 1GB -Description "Test quota" -SoftLimit -ThresholdConfigurations $Using:thresholds } ``` #### Get-FSxFSRMQuota Get-FSxFSRMQuota Retrieves one or more quotas from your file system. The command returns details about quota configurations, including size limits, thresholds, and current usage. **Parameters:** + `Folder (string)` - Optional. The folder path from which to retrieve quotas. If you don't specify a folder path, the command returns all quotas on the file system. **Examples:** **1. Get all existing quotas on the file system.** ``` Invoke-Command -ComputerName $FSxWindowsRemotePowerShellEndpoint -ConfigurationName FSxRemoteAdmin -ScriptBlock { Get-FSxFSRMQuota } ``` #### Remove-FSxFSRMQuota Remove-FSxFSRMQuota Removes a quota from a specified folder on your file system. **Parameters:** + `Folder (string)` - Required. The folder path from which to remove the quota. + `PassThru (boolean)` - Optional. If set to true, returns the removed quota object. **Examples:** **1. Remove a quota.** ``` Invoke-Command -ComputerName $FSxWindowsRemotePowerShellEndpoint -ConfigurationName FSxRemoteAdmin -ScriptBlock { Remove-FSxFSRMQuota -Folder "share\test" -PassThru } ``` #### Set-FSxFSRMQuota Set-FSxFSRMQuota Modifies the configuration of an existing quota. **Parameters:** + `Folder (string)` - Required. The folder path that contains the quota to modify. + `Description (string)` - Optional. A new description for the quota. + `Size (string)` - Optional. The new size limit for the quota. + `SoftLimit (boolean)` - Optional. If set to true, changes the quota to a soft limit, allowing users to exceed the limit while logging violations. + `Disabled (boolean)` - Optional. If set to true, disables the quota. If set to false, enables the quota. + `ThresholdConfigurations (array)` - Optional. An array of new threshold configurations. Each threshold configuration has the following properties: + `ThresholdPercentage (number)`: The percentage of the quota limit at which to trigger actions. Enter a value between 0 and 250. + `Action (array)`: One or more actions to take when the threshold is reached. Each action has the following properties: + `ActionType`: The type of action to perform. You can specify the following values: 1. `Event`: Logs an event to the file system's event log. When you specify Event, you must also specify the following properties: + `EventType`: Information, Warning, or Error + `MessageBody`: The message text to log with the event. 1. `Report`: Generates a storage usage report. + `PassThru (boolean)` - Optional. If set to true, returns the modified quota object. **Examples:** **1. Modify quota size and description.** ``` Invoke-Command -ComputerName $FSxWindowsRemotePowerShellEndpoint -ConfigurationName FSxRemoteAdmin -ScriptBlock { Set-FSxFSRMQuota -Folder "share\department" -Size 2GB -Description "Updated quota for department share" } ``` **2. Disable a Quota** ``` Invoke-Command -ComputerName $FSxWindowsRemotePowerShellEndpoint -ConfigurationName FSxRemoteAdmin -ScriptBlock { Set-FSxFSRMQuota -Folder "share\department" -Disabled: $true } ``` #### Update-FSxFSRMQuota Update-FSxFSRMQuota Recalculates the current usage statistics for a quota by scanning the folder to determine the actual amount of space being used. **Parameters:** + `Folder (string)` - Required. The folder path that contains the quota to update. + `PassThru (boolean)` - Optional. If set to true, returns the updated quota object. **Examples:** **1. Recalculates the current usage statistics for a specified quota.** ``` Invoke-Command -ComputerName $FSxWindowsRemotePowerShellEndpoint -ConfigurationName FSxRemoteAdmin -ScriptBlock { Update-FSxFSRMQuota -Folder "share\department" -PassThru } ``` ### Quota Template Commands Template Commands #### New-FSxFSRMQuotaTemplate New-FSxFSRMQuotaTemplate Creates a new quota template that defines a reusable configuration for quotas. **Parameters:** + `Name (string)` - Required. A name for the quota template. + `Size (string)` - Required. The size limit that the quota template enforces. + `Description (string)` - Optional. A description for the quota template. + `SoftLimit (boolean)` - Optional. If set to true, creates a template for soft quotas that report usage but don't enforce the limit. + `ThresholdConfigurations (array)` - Optional. An array of threshold configurations that specify actions to take at different usage levels. Each configuration has the following properties: + `ThresholdPercentage (number)`: The percentage of the quota limit at which to trigger actions. Enter a value between 0 and 250. + `Action (array)`: One or more actions to take when the threshold is reached. Each action has the following properties: + `ActionType`: The type of action to perform. You can specify the following values: 1. `Event`: Logs an event to the file system's event log. When you specify Event, you must also specify the following properties: + `EventType`: Information, Warning, or Error + `MessageBody`: The message text to log with the event. 1. `Report`: Generates a storage usage report. **Examples:** **1. Create hard 1 GB limit template.** ``` Invoke-Command -ComputerName $FSxWindowsRemotePowerShellEndpoint -ConfigurationName FSxRemoteAdmin -ScriptBlock { New-FSxFSRMQuotaTemplate -Name "1GB Hard Limit" -Size 1GB -Description "Standard 1GB hard limit template" } ``` **2. Create a 5 GB soft limit template with a warning threshold at 90% usage** ``` $threshold = @{ ThresholdPercentage = 90 Action = @( @{ ActionType = "Event" EventType = "Warning" MessageBody = "Quota usage has reached 90% of the limit" } ) } $thresholds = [System.Collections.ArrayList]@() $thresholds.Add($threshold) Invoke-Command -ComputerName $FSxWindowsRemotePowerShellEndpoint -ConfigurationName FSxRemoteAdmin -ArgumentList $thresholds -ScriptBlock { param($thresholds) New-FSxFSRMQuotaTemplate -Name "5GB Soft Limit" -Size 5GB -Description "5GB soft limit with 90% warning" -SoftLimit -ThresholdConfigurations $Using:thresholds } ``` #### Get-FSxFSRMQuotaTemplate Get-FSxFSRMQuotaTemplate Retrieves one or more quota templates from your file system. **Parameters:** + `Name (string)` - Optional. The name of a specific quota template to retrieve. If you don't specify a name, the command returns all quota templates. **Examples:** **1. Retrieve all quota templates on the file system.** ``` Invoke-Command -ComputerName $FSxWindowsRemotePowerShellEndpoint -ConfigurationName FSxRemoteAdmin -ScriptBlock { Get-FSxFSRMQuotaTemplate } ``` #### Set-FSxFSRMQuotaTemplate Set-FSxFSRMQuotaTemplate Modifies the properties of a quota template. **Parameters:** + `Name (string)` - Required. The name of the quota template to modify. + `Description (string)` - Optional. A new description for the template. + `Size (string)` - Optional. The new size limit for the template. + `SoftLimit (boolean)` - Optional. If set to true, changes the template to create soft quotas that report usage but don't enforce the limit. + `ThresholdConfigurations (array)` - Optional. An array of threshold configurations that specify actions to take at different usage levels. Each configuration has the following properties: + `ThresholdPercentage (number)`: The percentage of the quota limit at which to trigger actions. Enter a value between 0 and 250. + `Action (array)`: One or more actions to take when the threshold is reached. Each action has the following properties: + `ActionType`: The type of action to perform. You can specify the following values: 1. `Event`: Logs an event to the file system's event log. When you specify Event, you must also specify the following properties: + `EventType`: Information, Warning, or Error + `MessageBody`: The message text to log with the event. 1. `Report`: Generates a storage usage report. + `UpdateDerived (boolean)` - Optional. If set to true, updates all quotas that were created from this template. + `UpdateDerivedMatching (boolean)` - Optional. If set to true, updates only quotas that were created from this template and have not been modified since creation. + `PassThru (boolean)` - Optional. If set to true, returns the modified template object. **Examples:** **1. Modifies the size and description of a quota template.** ``` Invoke-Command -ComputerName $FSxWindowsRemotePowerShellEndpoint -ConfigurationName FSxRemoteAdmin -ScriptBlock { Set-FSxFSRMQuotaTemplate -Name "5GB Soft Limit" -Size 10GB -Description "Updated to 10GB soft limit" } ``` **2. Modifies a quota template and updates all quotas that were created from the template.** ``` Invoke-Command -ComputerName $FSxWindowsRemotePowerShellEndpoint -ConfigurationName FSxRemoteAdmin -ScriptBlock { Set-FSxFSRMQuotaTemplate -Name "1GB Hard Limit" -Size 2GB -UpdateDerived } ``` #### Reset-FSxFSRMQuota Reset-FSxFSRMQuota Resets a quota to match the settings of a specified template. #### Parameters Parameters + `Folder (string)` - Required. The folder path that contains the quota to reset. + `Template (string)` - Required. The name of the quota template to apply. #### Examples Examples **Examples: Reset a quota to match the settings defined in a quota template.** ``` Invoke-Command -ComputerName $FSxWindowsRemotePowerShellEndpoint -ConfigurationName FSxRemoteAdmin -ScriptBlock { Reset-FSxFSRMQuota -Folder "share\department" -Template "1GB Hard Limit" } ``` ### Auto Quota Commands Auto Quota Commands #### New-FSxFSRMAutoQuota Create Auto Quota The `New-FSxFSRMAutoQuota` command creates an auto apply quota on a specified folder. An auto apply quota automatically generates quotas based on the specified template for each existing subfolder and any new subfolders created in the specified folder. ##### Parameters Parameters + `Folder (string)` - Required. The folder path where the auto apply quota will be created. + `Template (string)` - Optional. The name of an existing quota template to use for the auto apply quota. + `Disabled (boolean)` - Optional. If set to true, creates the auto apply quota in a disabled state. ##### Examples Examples **1. Create an auto apply quota that automatically applies a specified template to all subfolders.** ``` Invoke-Command -ComputerName $FSxWindowsRemotePowerShellEndpoint -ConfigurationName FSxRemoteAdmin -ScriptBlock { New-FSxFSRMAutoQuota -Folder "share\department" -Template "250 MB Extended Limit" } ``` #### Get-FSxFSRMAutoQuota Retrieve Auto Quotas The `Get-FSxFSRMAutoQuota` command retrieves one or more auto apply quotas from your file system. ##### Parameters Parameters + `Folder (string)` - Optional. The folder path from which to retrieve auto apply quotas. You can also use `...` at the end of the path to include all subfolders. If you don't specify a folder path, the command returns all auto apply quotas on the file system. ##### Examples Examples **1. Retrieve all auto apply quotas on the file system.** ``` Invoke-Command -ComputerName $FSxWindowsRemotePowerShellEndpoint -ConfigurationName FSxRemoteAdmin -ScriptBlock { Get-FSxFSRMAutoQuota } ``` #### Remove-FSxFSRMAutoQuota Remove Auto Quota The `Remove-FSxFSRMAutoQuota` command removes an auto-apply quota from a specified folder. When you remove an auto apply quota, the command also removes all quotas from subfolders that were derived from the associated quota template. ##### Parameters Parameters + `Folder (string)` - Required. The folder path from which to remove the auto apply quota. + `PassThru (boolean)` - Optional. If set to true, returns the removed auto apply quota object. ##### Examples Examples **1. Remove an auto apply quota from a specific folder.** ``` Invoke-Command -ComputerName $FSxWindowsRemotePowerShellEndpoint -ConfigurationName FSxRemoteAdmin -ScriptBlock { Remove-FSxFSRMAutoQuota -Folder "share\department" -PassThru } ``` #### Set-FSxFSRMAutoQuota Modify Auto Quota The `Set-FSxFSRMAutoQuota` command modifies the configuration settings of an auto apply quota. ##### Parameters Parameters + `Folder (string)` - Required. The folder path that contains the auto apply quota to modify. + `Template (string)` - Optional. The name of a quota template to apply. + `Disabled (boolean)` - Optional. If set to true, disables the auto apply quota. If set to false, enables the auto apply quota. + `UpdateDerived (boolean)` - Optional. If set to true, updates all existing quotas that were derived from this auto apply quota. + `UpdateDerivedMatching (boolean)` - Optional. If set to true, updates only derived quotas that have not been modified since creation. + `PassThru (boolean)` - Optional. If set to true, returns the modified auto apply quota object. ##### Examples Examples **1. Change the quota template used by an auto apply quota.** ``` Invoke-Command -ComputerName $FSxWindowsRemotePowerShellEndpoint -ConfigurationName FSxRemoteAdmin -ScriptBlock { Set-FSxFSRMAutoQuota -Folder "share\department" -Template "100 MB Limit" } ``` **2. Disable an auto apply quota and update all quotas that were derived from it.** ``` Invoke-Command -ComputerName $FSxWindowsRemotePowerShellEndpoint -ConfigurationName FSxRemoteAdmin -ScriptBlock { Set-FSxFSRMAutoQuota -Folder "share\department" -Disabled: $true -UpdateDerived } ``` #### Update-FSxFSRMAutoQuota Update Auto Quota The `Update-FSxFSRMAutoQuota` command recalculates the properties of an auto apply quota and the quotas that are derived from it by scanning the folder to determine the actual amount of space being used. ##### Parameters Parameters + `Folder (string)` - Required. The folder path that contains the auto apply quota to update. + `PassThru (boolean)` - Optional. If set to true, returns the updated auto apply quota object. ##### Examples Examples **1. Recalculate the usage statistics and return the updated auto apply quota object.** ``` Invoke-Command -ComputerName $FSxWindowsRemotePowerShellEndpoint -ConfigurationName FSxRemoteAdmin -ScriptBlock { Update-FSxFSRMAutoQuota -Folder "share\department" -PassThru } ``` # File Groups File Groups File groups define logical collections of file name patterns that you must use when configuring [file screens](fsrm-file-screening.md), and that you can optionally use when generating [storage reports](fsrm-storage-reports.md). A file group contains include patterns (files to match) and exclude patterns (files to exclude from matches), which you reference by the file group name rather than specifying individual patterns each time. ## How file groups are used File group usage File groups are required for the following FSRM features: + **File screens** - You must specify one or more file groups to define which file types to block or monitor. + **File screen exceptions** - You must specify one or more file groups to define which file types to allow despite blocking file screens in parent folders. + **File screen templates** - You must specify one or more file groups to define which file types the template will block or monitor. File groups are optional for the following FSRM features: + **Storage reports** - You can optionally filter reports by file group to analyze storage usage for specific file types. For example, you can generate a report showing only audio and video files. ## File name patterns File name patterns File groups use wildcard patterns to match file names. You can specify both include patterns (files to match) and exclude patterns (files to exclude from matches). FSRM supports the following wildcards: + **Asterisk (\$1)** - Matches zero or more characters + **Question mark (?)** - Matches exactly one character For example, the pattern `*.doc*` matches files like `report.doc` , `report.docx`, and `document.doc`, while the exclude pattern ` ~$*` excludes temporary files created by Microsoft Office applications. ## Default file groups Default file groups When you enable FSRM on your file system, the following file groups are created automatically: **Audio and Video Files** Matches common audio and video file formats including `*.mp3`, ` *.wav`, `*.avi`, `*.mp4`, `*.mpeg`, and `*.wmv` **Backup Files** Matches backup file formats including `*.bak`, `*.backup`, and `*.old` **Compressed Files** Matches archive and compressed file formats including `*.zip`, ` *.rar`, `*.7z`, `*.gz`, and `*.tar` **E-mail Files** Matches email message and mailbox formats including `*.eml`, ` *.msg`, and `*.pst` **Executable Files** Matches executable and script file formats including `*.exe`, ` *.dll`, `*.com`, `*.bat`, `*.cmd`, and `*.vbs` **Image Files** Matches common image file formats including `*.jpg`, ` *.jpeg`, `*.png`, `*.gif`, `*.bmp`, and `*.tif` **Office Files** Matches Microsoft Office document formats including `*.doc`, ` *.docx`, `*.xls`, `*.xlsx`, `*.ppt`, and `*.pptx` **System Files** Matches Windows system file formats including `*.sys`, ` *.dll`, `*.ocx`, and `*.drv` **Temporary Files** Matches temporary file formats including `*.tmp`, `*.temp`, and `~*` **Text Files** Matches text-based file formats including `*.txt`, `*.log` , `*.csv`, and `*.xml` **Web Page Files** Matches web content file formats including `*.html`, ` *.htm`, `*.asp`, `*.aspx`, `*.php`, and `*.js` You can use these default file groups immediately in file screens and storage reports, or you can modify them to match your specific requirements. ## File group management commands Management commands FSRM provides PowerShell commands for creating and managing file groups. Use these commands to define custom file groups that match your organization's file management policies. **Note** All the examples in this page assume that you have defined the ` $FSxWindowsRemotePowerShellEndpoint` variable with your file system's Windows Remote PowerShell endpoint. You can find this endpoint in the AWS FSx console on your file system's details page, or by using the AWS CLI ` describe-file-systems` command. ### New-FSxFSRMFileGroup New-FSxFSRMFileGroup Creates a file group that defines a logical collection of file name patterns. These patterns can be used for file screens, file screen exceptions, and storage reports. **Parameters:** + `Name (string)` - Required. A name for the file group. + `Description (string)` - Optional. A description for the file group. + `IncludePattern (array)` - Optional. An array of pattern strings that specify files to include. + `ExcludePattern (array)` - Optional. An array of pattern strings that specify files to exclude. **Examples:** 1. Create a file group for text files. ``` Invoke-Command -ComputerName $FSxWindowsRemotePowerShellEndpoint -ConfigurationName FSxRemoteAdmin -ScriptBlock { New-FSxFSRMFileGroup -Name "My Text Files" -IncludePattern "*.txt" } ``` 1. Create a file group for source code with include and exclude patterns. ``` $includePatterns = @("*.cpp", "*.h", "*.cs", "*.py") $excludePatterns = @("*.tmp", "*.bak") Invoke-Command -ComputerName $FSxWindowsRemotePowerShellEndpoint -ConfigurationName FSxRemoteAdmin -ArgumentList @($includePatterns, $excludePatterns) -ScriptBlock { param($includePatterns, $excludePatterns) New-FSxFSRMFileGroup -Name "Source Code" -Description "Programming source files" -IncludePattern $includePatterns -ExcludePattern $excludePatterns } ``` ### Get-FSxFSRMFileGroup Get-FSxFSRMFileGroup Retrieves one or more file groups from your file system. File groups define collections of file patterns used in file screening and reporting. **Parameters:** + `Name (array)` - Optional. An array of names of file groups to retrieve. If you don't specify a name, the command returns all file groups on the file system. **Examples:** 1. Retrieve all file groups on the file system. ``` Invoke-Command -ComputerName $FSxWindowsRemotePowerShellEndpoint -ConfigurationName FSxRemoteAdmin -ScriptBlock { Get-FSxFSRMFileGroup } ``` ### Remove-FSxFSRMFileGroup Remove-FSxFSRMFileGroup Removes one or more file groups from your file system. After removal, the file group cannot be used in file screens or file screen exceptions. **Parameters:** + `Name (array)` - Required. An array of names of file groups to remove. + `PassThru (boolean)` - Optional. If set to true, returns the removed file group object. **Examples:** 1. Remove a single file group. ``` Invoke-Command -ComputerName $FSxWindowsRemotePowerShellEndpoint -ConfigurationName FSxRemoteAdmin -ScriptBlock { Remove-FSxFSRMFileGroup -Name "My Text Files" -PassThru } ``` ### Set-FSxFSRMFileGroup Set-FSxFSRMFileGroup Modifies the properties of existing file groups. **Parameters:** + `Name (array)` - Required. An array of names of file groups to modify. + `Description (string)` - Optional. A new description for the file group. + `IncludePattern (array)` - Optional. A new array of pattern strings that specify files to include. + `ExcludePattern (array)` - Optional. A new array of pattern strings that specify files to exclude. + `PassThru (boolean)` - Optional. If set to true, returns the modified file group object. **Examples:** 1. Update the description and patterns for a file group. ``` $includePatterns = @("*.docx", "*.pdf", "*.rtf") $excludePatterns = @("~$*", "*.tmp") Invoke-Command -ComputerName $FSxWindowsRemotePowerShellEndpoint -ConfigurationName FSxRemoteAdmin -ArgumentList @($includePatterns, $excludePatterns) -ScriptBlock { param($includePatterns, $excludePatterns) Set-FSxFSRMFileGroup -Name "Documents" -Description "Updated document types" -IncludePattern $includePatterns -ExcludePattern $excludePatterns -PassThru } ``` # File Screening File Screening File screening controls which types of files users can save to folders on your file system. File screening helps you enforce storage policies, prevent unauthorized file types, and maintain compliance with organizational requirements. **Note** File screens use file groups to define which file types to block or monitor. For more information about creating and managing file groups, see [File Groups](fsrm-file-groups.md). FSRM supports two types of file screens: 1. **Active file screens** - Block users from saving files that match the specified file groups and generate notifications when users attempt to save blocked files. Use active file screens when you need to enforce strict policies about which file types are allowed in specific folders. 1. **Passive file screens** - Monitor and log when users save files that match the specified file groups, but do not prevent the save operation. Use passive file screens when you want to track file usage patterns without disrupting user workflows. ## File screen templates Templates File screen templates provide a reusable configuration that defines file screening settings, including which file groups to block or monitor and what notifications to generate. After you create a file screen template, you can apply it to multiple folders without having to reconfigure the same settings each time. When you update a file screen template, you can optionally apply the changes to all file screens that were created from that template. Using file screen templates offers several benefits: + **Consistency** - Ensure that similar folders have identical file screening configurations + **Efficiency** - Apply file screening settings to multiple folders quickly + **Maintainability** - Update file screening settings across multiple folders by modifying the template ## File screen exceptions Exceptions File screen exceptions override file screening rules that would otherwise apply to a folder and all its subfolders. When you create a file screen exception, you specify which file groups to allow despite any blocking file screens in parent folders. File screen exceptions are useful when you need to permit specific file types in certain subfolders while maintaining broader restrictions at higher levels of the folder hierarchy. For example, you might block executable files across an entire share but create an exception for a specific subfolder where administrators need to store installation files. ## File screening notifications Notifications When users attempt to save files that are blocked by an active file screen, FSRM can generate notifications to alert administrators or provide information to users. You can configure the following types of notifications: + **Event logging** - Log an event to Amazon CloudWatch or Amazon Kinesis Data Firehose for monitoring and analysis. You can specify the event's severity level (Information, Warning, or Error) and provide a custom message body. Event logging is useful for tracking file screen violations and integrating with existing monitoring systems. + **Storage reports** - Generate a storage usage report that provides detailed information about file screening activity. Storage reports help you identify patterns in file save attempts and make informed decisions about file screening policies. For more information, see [Storage Reports](fsrm-storage-reports.md). ## File screening management commands Management commands You can access three families of FSx remote PowerShell commands for managing file screens: 1. **File screen commands** - Create, retrieve, modify, remove, and reset individual file screens on specific folders. Use these commands when you need to manage file screens on a folder-by-folder basis. 1. **File screen template commands** - Create, retrieve, modify, and remove file screen templates that define reusable file screening configurations. Use these commands to establish standard file screening policies that you can apply across multiple folders. 1. **File screen exception commands** - Create, retrieve, modify, and remove file screen exceptions that override file screening rules in parent folders. Use these commands when you need to allow specific file types in certain subfolders while maintaining broader restrictions. ### List of File Screening FSx remote PowerShell commands PowerShell commands **Note** All the examples in this page assume that you have defined the ` $FSxWindowsRemotePowerShellEndpoint` variable with your file system's Windows Remote PowerShell endpoint. You can find this endpoint in the Amazon FSx console on your file system's details page, or by using the AWS CLI `describe-file-systems` command. ### File screen commands File screen commands #### New-FSxFSRMFileScreen New-FSxFSRMFileScreen Creates a file screen that blocks users from saving specified types of files to a folder. **Parameters:** + `Folder (string)` - Required. The folder path where the file screen will be applied. + `Description (string)` - Optional. A description for the file screen. + `IncludeGroup (array)` - Optional. An array of file group names that specify which files to block or monitor. + `Active (boolean)` - Optional. If set to true, creates an active file screen that blocks files. If set to false, creates a passive file screen that only monitors files. Default is true. + `Template (string)` - Optional. The name of an existing file screen template to use. + `NotificationConfigurations (array)` - Optional. An array of configurations for notifications when users attempt to save blocked files. Each configuration has the following properties: + `ActionType (string)`: The type of action to perform. You can specify the following values: 1. `Event`: Logs an event to the file system's event log. When you specify Event, you must also specify the following properties: + `EventType (string)`: Information, Warning, or Error + `MessageBody (string)`: The message text to log with the event. 1. `Report`: Generates a storage usage report. When you specify Report, you must also specify: + `ReportType (string)`: The type of report. You can specify the following values: `DuplicateFiles`, `FilesByFileGroup`, `FilesByOwner`, `FilesByProperty`, `LargeFiles`, `LeastRecentlyAccessed`, `MostRecentlyAccessed`, or `QuotaUsage`. **Examples:** 1. Create a basic active file screen that blocks Audio Files. ``` Invoke-Command -ComputerName $FSxWindowsRemotePowerShellEndpoint -ConfigurationName FSxRemoteAdmin -ScriptBlock { New-FSxFSRMFileScreen -Folder "share\department" -IncludeGroup "Audio and Video Files" } ``` 1. Create a file screen that blocks video files and generates an event log entry when a user attempts to save a video file. ``` $notifications = [System.Collections.ArrayList]@() $eventNotification = @{ ActionType = "Event" EventType = "Warning" MessageBody = "File screen violation detected" } $null = $notifications.Add($eventNotification) Invoke-Command -ComputerName $FSxWindowsRemotePowerShellEndpoint -ConfigurationName FSxRemoteAdmin -ArgumentList $notifications -ScriptBlock { param($notifications) New-FSxFSRMFileScreen -Folder "share\projects" -IncludeGroup "Audio and Video Files" -NotificationConfigurations $Using:notifications } ``` #### Get-FSxFSRMFileScreen Get-FSxFSRMFileScreen Retrieves one or more file screens from your file system. **Parameters:** + `Folder (string)` - Optional. The folder path from which to retrieve file screens. If you don't specify a folder path, the command returns all file screens on the file system. **Examples:** 1. Retrieve all file screens on the file system. ``` Invoke-Command -ComputerName $FSxWindowsRemotePowerShellEndpoint -ConfigurationName FSxRemoteAdmin -ScriptBlock { Get-FSxFSRMFileScreen } ``` #### Set-FSxFSRMFileScreen Set-FSxFSRMFileScreen Modifies the properties of an existing file screen. **Parameters:** + `Folder (string)` - Required. The folder path that contains the file screen to modify. + `Description (string)` - Optional. A new description for the file screen. + `IncludeGroup (array)` - Optional. A new array of file group names that define which files to block or monitor. + `Active (boolean)` - Optional. If set to true, sets the file screen to active mode (blocking). If set to false, sets the file screen to passive mode (monitoring only). Default is true. + `NotificationConfigurations (array)` - Optional. A new array of notification configurations. + `PassThru (boolean)` - Optional. If set to true, returns the modified file screen object. **Examples:** 1. Modify the description and file groups for a file screen. ``` $includeGroups = @("Audio and Video Files") Invoke-Command -ComputerName $FSxWindowsRemotePowerShellEndpoint -ConfigurationName FSxRemoteAdmin -ArgumentList $includeGroups -ScriptBlock { param($includeGroups) Set-FSxFSRMFileScreen -Folder "share\projects" -Description "Updated screen" -IncludeGroup $includeGroups } ``` 1. Set a file screen to active mode and add notifications. ``` $notifications = [System.Collections.ArrayList]@() $eventNotification = @{ ActionType = "Event" EventType = "Warning" MessageBody = "File screen violation detected" } $null = $notifications.Add($eventNotification) Invoke-Command -ComputerName $FSxWindowsRemotePowerShellEndpoint -ConfigurationName FSxRemoteAdmin -ArgumentList $notifications -ScriptBlock { param($notifications) Set-FSxFSRMFileScreen -Folder "share\projects" -Active: $true -NotificationConfigurations $Using:notifications -PassThru } ``` #### Remove-FSxFSRMFileScreen Remove-FSxFSRMFileScreen Removes a file screen from a specified folder. **Parameters:** + `Folder (string)` - Required. The folder path from which to remove the file screen. + `PassThru (boolean)` - Optional. If set to true, returns the removed file screen object. **Examples:** 1. Remove a file screen from a specific folder. ``` Invoke-Command -ComputerName $FSxWindowsRemotePowerShellEndpoint -ConfigurationName FSxRemoteAdmin -ScriptBlock { Remove-FSxFSRMFileScreen -Folder "share\projects" -PassThru } ``` #### Reset-FSxFSRMFileScreen Reset-FSxFSRMFileScreen Resets a file screen to match the settings of a specified template. **Parameters:** + `Folder (string)` - Required. The folder path that contains the file screen to reset. + `Template (string)` - Required. The name of an existing file screen template to apply. **Examples:** 1. Reset a file screen to match the settings defined in a file screen template. ``` Invoke-Command -ComputerName $FSxWindowsRemotePowerShellEndpoint -ConfigurationName FSxRemoteAdmin -ScriptBlock { Reset-FSxFSRMFileScreen -Folder "share\department" -Template "Block Audio Files" } ``` ### File Screen Template Commands Template Commands #### Get-FSxFSRMFileScreenTemplate Get Template The `Get-FSxFSRMFileScreenTemplate` command retrieves one or more file screen templates from your file system. ##### Parameters Parameters + `Name (array)` - Optional. An array of names of file screen templates to retrieve. If you don't specify a name, the command returns all file screen templates on the file system. ##### Examples Examples 1. Retrieve all file screen templates. ``` Invoke-Command -ComputerName $FSxWindowsRemotePowerShellEndpoint -ConfigurationName FSxRemoteAdmin -ScriptBlock { Get-FSxFSRMFileScreenTemplate } ``` #### New-FSxFSRMFileScreenTemplate New Template The `New-FSxFSRMFileScreenTemplate` command creates a file screen template that defines a reusable configuration for file screens. The template specifies which file groups to block and what notifications to generate when users attempt to save blocked files. ##### Parameters Parameters + `Name (string)` - Required. A name for the file screen template. + `Description (string)` - Optional. A description for the file screen template. + `IncludeGroup (array)` - Optional. An array of file group names that specify which files to block or monitor. + `Active (boolean)` - Optional. If set to true, creates an active file screen template that blocks files. If set to false, creates a passive template that only monitors files. Default is true. + `NotificationConfigurations (array)` - Optional. An array of configurations for notifications when users attempt to save blocked files. Each configuration has the following properties: + `ActionType (string)`: The type of action to perform. You can specify the following values: 1. `Event`: Logs an event to the file system's event log. When you specify Event, you must also specify the following properties: + `EventType (string)`: Information, Warning, or Error + `MessageBody (string)`: The message text to log with the event. 1. `Report`: Generates a storage usage report. When you specify Report, you must also specify: + `ReportType (string)`: The type of report. You can specify the following values: `DuplicateFiles`, `FilesByFileGroup`, `FilesByOwner`, `FilesByProperty`, `LargeFiles`, `LeastRecentlyAccessed`, `MostRecentlyAccessed`, or `QuotaUsage` ##### Examples Examples 1. Create a file screen template with notifications. ``` $notifications = [System.Collections.ArrayList]@() $eventNotif = @{ ActionType = "Event" EventType = "Warning" MessageBody = "Blocked file detected" } $null = $notifications.Add($eventNotif) Invoke-Command -ComputerName $FSxWindowsRemotePowerShellEndpoint -ConfigurationName FSxRemoteAdmin -ArgumentList $notifications -ScriptBlock { param($notifications) New-FSxFSRMFileScreenTemplate -Name "Block Executables" -Description "Blocks executable files" -IncludeGroup "Executable Files" -Active: $true -NotificationConfigurations $Using:notifications } ``` #### Remove-FSxFSRMFileScreenTemplate Remove Template The `Remove-FSxFSRMFileScreenTemplate` command removes one or more file screen templates from your file system. When you remove a template, file screens that were created from that template remain unchanged. ##### Parameters Parameters + `Name (array)` - Required. An array of names of file screen templates to remove. + `PassThru (boolean)` - Optional. If set to true, returns the removed file screen template object. ##### Examples Examples 1. Remove a single file screen template. ``` Invoke-Command -ComputerName $FSxWindowsRemotePowerShellEndpoint -ConfigurationName FSxRemoteAdmin -ScriptBlock { Remove-FSxFSRMFileScreenTemplate -Name "Block Executables" -PassThru } ``` #### Set-FSxFSRMFileScreenTemplate Set Template The `Set-FSxFSRMFileScreenTemplate` command modifies the properties of existing file screen templates. Optionally updates file screens that were created using the modified templates. ##### Parameters Parameters + `Name (array)` - Required. An array of names of file screen templates to modify. + `Description (string)` - Optional. A new description for the template. + `IncludeGroup (array)` - Optional. A new array of file group names that define which files to block or monitor. + `Active (boolean)` - Optional. If set to true, sets the template to active mode (blocking). If set to false, sets the template to passive mode (monitoring). Default is true. + `NotificationConfigurations (array)` - Optional. A new array of notification configurations. + `UpdateDerived (boolean)` - Optional. If set to true, updates all existing file screens created from this template, regardless of any modifications made to those file screens. + `UpdateDerivedMatching (boolean)` - Optional. If set to true, updates only file screens that have not been modified since their creation from this template. + `PassThru (boolean)` - Optional. If set to true, returns the modified file screen template object. ##### Examples Examples 1. Update a file screen template with new file groups. ``` $includeGroups = @("Audio and Video Files") Invoke-Command -ComputerName $FSxWindowsRemotePowerShellEndpoint -ConfigurationName FSxRemoteAdmin -ArgumentList $includeGroups -ScriptBlock { param($includeGroups) Set-FSxFSRMFileScreenTemplate -Name "Block Executables" -IncludeGroup $includeGroups } ``` 2. Update a file screen template to active mode and update all derived file screens. ``` Invoke-Command -ComputerName $FSxWindowsRemotePowerShellEndpoint -ConfigurationName FSxRemoteAdmin -ScriptBlock { Set-FSxFSRMFileScreenTemplate -Name "Block Executables" -Active: $true -UpdateDerived } ``` ### File Screen Exception Commands Exception Commands #### New-FSxFSRMFileScreenException New Exception The `New-FSxFSRMFileScreenException` command creates a file screen exception that overrides any file screening rules that would otherwise apply to a folder and all its subfolders. This allows specific file types to be created in the exception folder even if they are blocked by file screens in parent folders. ##### Parameters Parameters + `Folder (string)` - Required. The folder path where the file screen exception will be applied. The exception applies to this folder and all its subfolders. + `Description (string)` - Optional. A description for the file screen exception. + `IncludeGroup (array)` - Optional. An array of file group names that specify which files to allow despite any blocking file screens that would otherwise apply from parent folders. ##### Examples Examples 1. Create a file screen exception for a specific folder and file group. ``` Invoke-Command -ComputerName $FSxWindowsRemotePowerShellEndpoint -ConfigurationName FSxRemoteAdmin -ScriptBlock { New-FSxFSRMFileScreenException -Folder "share\department" -IncludeGroup "Text Files" } ``` 2. Create a file screen exception with multiple file groups. ``` $includeGroups = @("Audio and Video Files", "Documents") Invoke-Command -ComputerName $FSxWindowsRemotePowerShellEndpoint -ConfigurationName FSxRemoteAdmin -ArgumentList $includeGroups -ScriptBlock { param($includeGroups) New-FSxFSRMFileScreenException -Folder "share\projects" -Description "Allow media files in project folder" -IncludeGroup $includeGroups } ``` #### Get-FSxFSRMFileScreenException Get Exception The `Get-FSxFSRMFileScreenException` command retrieves one or more file screen exceptions from your file system. ##### Parameters Parameters + `Folder (string)` - Optional. The folder path from which to retrieve file screen exceptions. If you don't specify a folder path, the command returns all file screen exceptions on the file system. ##### Examples Examples 1. Retrieve all file screen exceptions on the file system. ``` Invoke-Command -ComputerName $FSxWindowsRemotePowerShellEndpoint -ConfigurationName FSxRemoteAdmin -ScriptBlock { Get-FSxFSRMFileScreenException } ``` 2. Retrieve the file screen exception for a specific folder. ``` Invoke-Command -ComputerName $FSxWindowsRemotePowerShellEndpoint -ConfigurationName FSxRemoteAdmin -ScriptBlock { Get-FSxFSRMFileScreenException -Folder "share\department" } ``` #### Remove-FSxFSRMFileScreenException Remove Exception The `Remove-FSxFSRMFileScreenException` command removes a file screen exception from a specified folder. After removal, the folder and its subfolders will be subject to any file screening rules from parent folders that were previously overridden by the exception. ##### Parameters Parameters + `Folder (string)` - Required. The folder path from which to remove the file screen exception. + `PassThru (boolean)` - Optional. If set to true, returns the removed file screen exception object. ##### Examples Examples 1. Remove a file screen exception from a specific folder. ``` Invoke-Command -ComputerName $FSxWindowsRemotePowerShellEndpoint -ConfigurationName FSxRemoteAdmin -ScriptBlock { Remove-FSxFSRMFileScreenException -Folder "share\projects" -PassThru } ``` #### Set-FSxFSRMFileScreenException Set Exception The `Set-FSxFSRMFileScreenException` command modifies the properties of a file screen exception. ##### Parameters Parameters + `Folder (string)` - Required. The folder path that contains the file screen exception to modify. + `Description (string)` - Optional. A new description for the file screen exception. + `IncludeGroup (array)` - Optional. A new array of file group names that define which files to allow despite any blocking file screens that would otherwise apply from parent folders. + `PassThru (boolean)` - Optional. If set to true, returns the modified file screen exception object. ##### Examples Examples 1. Update the allowed file groups for a file screen exception. ``` $includeGroups = @("Audio and Video Files") Invoke-Command -ComputerName $FSxWindowsRemotePowerShellEndpoint -ConfigurationName FSxRemoteAdmin -ArgumentList $includeGroups -ScriptBlock { param($includeGroups) Set-FSxFSRMFileScreenException -Folder "share\projects" -IncludeGroup $includeGroups -PassThru } ``` # File Classification File Classification File classification automatically assigns metadata properties to files based on their content, location, or other attributes. Classification helps you organize files, enforce data management policies, and meet compliance requirements by identifying files that contain sensitive information, belong to specific business categories, or require retention periods. ## How file classification works How it works File classification uses a three-step process: 1. **Define properties** - Create classification property definitions that specify the types of metadata you want to assign to files, such as `"Data Sensitivity"` or `"ContainsPII"`. 1. **Create rules** - Configure classification rules that automatically assign property values to files based on criteria you specify, such as file content patterns or folder locations. For example, files that contain a pattern such as a Social Security Number `(XXX-XX-XXXX)` can be automatically classified as `ContainsPII=Yes`. 1. **Run classification** - Execute the classification process to scan files and apply the rules. You can run classification manually on demand, on a schedule, or continuously in the background. After classification is completed, you can use the assigned properties to generate storage reports, apply [File Management Tasks](fsrm-file-management.md), or search for files with specific characteristics. ## Classification property definitions Property definitions Classification property definitions specify the types of metadata that can be assigned to files. Each property definition has a name, a property type, and optionally a list of allowed values. For example, you might create a property called `"Data Sensitivity"` with an `OrderedList` Type and possible values: `Public`, `Internal`, `Confidential`, and `Restricted`. The following property types are supported: + `OrderedList` - An ordered list where values have a specific sequence (for example, Low, Medium, High). Use this type when the order of values matters for reporting or policy decisions. + `MultiChoice` - Allows multiple values to be selected from a list (for example, a file might be tagged with both "Financial" and "Legal" categories). + `SingleChoice` - Allows only one value to be selected from a list. + `String` - A single text value with no predefined options. + `MultiString` - Multiple text values with no predefined options. + `Integer` - A numeric value. + `YesNo` - A boolean value (true or false). + `DateTime` - A date and time value. Property definitions are reusable across multiple classification rules. After you create a property definition, you can reference it in any classification rule that needs to assign values for that property. ## Classification rules Classification rules Classification rules define the logic for automatically assigning property values to files. Each rule specifies: + Which property to set + What value to assign to that property + Where to apply the rule (which folders) + How to identify files that should receive the property value. You can use two classification mechanisms: ### Content Classifier Content Classifier Content Classifier scans file content for specific text patterns or regular expressions. Use this mechanism to identify files based on what they contain. Content Classifier provides three ways to match file content: + `ContentString` - Searches for case-insensitive text strings. Use this option when you want to find specific words or phrases regardless of capitalization. For example, searching for "confidential" will match "Confidential", "CONFIDENTIAL", and "confidential". + `ContentStringCaseSensitive` - Searches for case-sensitive text strings. Use this option when capitalization matters for your search. For example, searching for "SSN" will match "SSN" but not "ssn" or "Ssn". This is useful for acronyms, product codes, or other identifiers where case is significant. + `ContentRegularExpression` - Searches for patterns using regular expressions. Use this option when you need to match complex patterns or variable formats. For example, you can use regular expressions to detect: + Social Security numbers in the format 123-45-6789: ` \b\d{3}-\d{2}-\d{4}\b` + Credit card numbers with optional spaces or dashes: ` \b\d{4}[\s-]?\d{4}[\s-]?\d{4}[\s-]?\d{4}\b` + Email addresses, phone numbers, or other structured data You can specify multiple strings or patterns in a single rule and files will be classified if their content matches any of the specified values. ### Folder Classifier Folder Classifier Folder Classifier assigns property values based on where files are stored. Use this mechanism to classify files by their location in the folder hierarchy. For example: + Set a retention period property for all files in the Legal Documents folder + Mark all files in a specific project folder with a project identifier Additionally, you can use the `ReevaluateProperty` parameter to control what happens when classification runs on a file that already has a value for the property. You can select the following configurations: + `Never` - Only classify files that don't have a value for this property + `Overwrite` - Replace existing values when files change + `Aggregate` - Combine new values with existing values (for multi-value properties) ## Management properties Management properties Management properties are classification properties that apply to folders instead of files. You use management properties to organize and categorize folders in your file system hierarchy. Unlike file properties that are assigned automatically through classification rules, you set management properties manually using the ` Set-FSxFSRMMgmtProperty` command. To classify folders, use the `FolderUsage_MS` property. You can specify the following values: + `User Files` + `Group Share` + `Application Files` + `Backup and Archival` ## Running classification Running classification You can run file classification in three ways: 1. **Manual classification** - Use [Start-FSxFSRMClassification](#start-fsxfsrmclassification) to run classification immediately. This approach is useful for testing new rules or performing one-time classification tasks. 1. **Scheduled classification** - Use [Set-FSxFSRMClassification](#set-fsxfsrmclassification) to configure a schedule for automatic classification. You can schedule classification to run weekly or monthly at specific times. Scheduled classification is appropriate for most production environments where you want regular, predictable classification runs. 1. **Continuous classification** - Use [Set-FSxFSRMClassification](#set-fsxfsrmclassification) with the `Continuous` parameter to enable background classification that runs continuously. Continuous classification automatically classifies new and modified files shortly after they're created or changed. This approach provides the most up-to-date classification but consumes more system resources. When you start classification, you can specify a `RunDuration` to limit how long the process runs. If classification doesn't complete within the specified time, it stops and resumes during the next scheduled run or when you manually start it again. After classification completes, you can view the classification properties assigned to files by right clicking a file in Windows File Explorer, selecting **Properties**, and choosing the **Classification** tab. This tab displays all classification properties and their values for the file. ## Classification process management Process management You can monitor and control the classification process with the following commands: + [Get-FSxFSRMClassification](#get-fsxfsrmclassification) - Check the current status of classification (`Running`, `Queued`, `NotRunning`, or `Unknown`) + [Stop-FSxFSRMClassification](#stop-fsxfsrmclassification) - Stop a running or queued classification job + [Wait-FSxFSRMClassification](#wait-fsxfsrmclassification) - Pause script execution until classification completes or a timeout expires Use these commands to coordinate classification with other tasks. For example, you might wait for classification to complete before generating a storage report that depends on classified file properties. ## Classification best practices Best practices Follow these best practices to ensure efficient and effective file classification. ### 1. Performance considerations Performance Content-based classification is resource-intensive because FSRM must read and scan file content. + **Test rules on a small dataset first** - Before applying classification rules to your entire file system, test them on a representative sample of files to verify they work as expected and to estimate how long classification will take. + **Limit content scanning scope** - Content-based classification is resource-intensive because it requires reading file content. Use the `Namespace` parameter to limit rules to specific folders rather than scanning the entire file system. + **Use folder classification when possible** - Folder Classifier is much faster than Content Classifier because it doesn't need to read file contents. When files can be classified based on their location, use the Folder Classifier instead of Content Classifier. + **Schedule classification during off-peak hours** - Run scheduled classification during periods of low system activity to minimize impact on user performance. Avoid running classification during backup windows or other maintenance tasks. + **Set appropriate RunDuration limits** - Use the `RunDuration` parameter to prevent classification from running too long and impacting system performance. If classification doesn't complete within the time limit, it will resume during the next scheduled run. + **Monitor classification performance** - Use ` Get-FSxFSRMClassification` to check classification status and identify if classification is taking longer than expected. Long-running classification may indicate that rules need to be optimized or that the system needs more resources. ### 2. Rule design Rule design + **Use specific regular expressions** - When using `ContentRegularExpression`, write patterns that are as specific as possible to avoid false matches. Test regular expressions thoroughly before deploying them in production. + **Combine multiple patterns efficiently** - Instead of creating separate rules for similar patterns, combine them into a single rule with multiple `ContentString` or `ContentRegularExpression` values. This reduces the number of times FSRM needs to scan each file. + **Exclude unnecessary folders** - Use the `ExcludeNamespace` parameter in `Set-FSxFSRMClassification` to exclude temporary directories, and other locations that don't need classification. ### 3. Property management Property management + **Plan your property schema** - Design your classification properties before creating rules. Consider what properties you need for reporting, compliance, and file management policies. + **Document property definitions** - Use the Description field to explain what each property means and how it should be used. This helps other administrators understand your classification schema. ### 4. Ongoing maintenance Maintenance + **Review classification results regularly** - Generate storage reports to verify that classification is working as expected and that files are receiving the correct property values. + **Update rules as needed** - As your organization's data management requirements change, update classification rules to reflect new policies or compliance requirements. + **Clean up unused properties** - Remove property definitions and rules that are no longer needed to keep your classification configuration manageable. ## Classification management commands Management commands You can access four families of FSx remote PowerShell commands for managing file classification: 1. **Property definition commands** - Create and manage classification property definitions that specify the types of metadata you can assign to files. 1. **Classification rule commands** - Create and manage automatic classification rules that assign property values based on file content or location. 1. **Management property commands** - Set and retrieve classification properties on folders rather than files. 1. **Classification process commands** - Start, stop, monitor, and configure the classification process. ### List of File Classification FSx remote PowerShell commands PowerShell commands **Note** All the examples in this page assume that you have defined the ` $FSxWindowsRemotePowerShellEndpoint` variable with your file system's Windows Remote PowerShell endpoint. You can find this endpoint in the Amazon FSx console on your file system's details page, or by using the AWS CLI `describe-file-systems` command. ### Property Definition Commands Property Definition Commands #### New-FSxFSRMClassificationPropertyDefinition New-FSxFSRMClassificationPropertyDefinition `New-FSxFSRMClassificationPropertyDefinition`: Creates a classification property definition that can be used to classify files. Property definitions define the attributes that can be assigned to files through classification rules. **Parameters:** + `Name (string)` - Required. A name for the property definition. + `DisplayName (string)` - Optional. A display name for the property definition. + `Description (string)` - Optional. A description for the property definition. + `Type (string)` - Required. The type of the classification property. You can specify the following values: + `OrderedList`: An ordered list of possible values + `MultiChoice`: Multiple choice selection from possible values + `SingleChoice`: Single choice from possible values + `String`: Single text string + `MultiString`: Multiple text strings + `Integer`: Numeric value + `YesNo`: Boolean value + `DateTime`: Date and time value + `PossibleValueConfigurations (array)` - Optional. An array of configurations for OrderedList, MultiChoice, or SingleChoice property types. Each configuration has the following properties: + `Name (string)`: The name of the value (required) + `Description (string)`: A description of the value (optional) + `Parameters (array)` - Optional. An array of strings in `"name=value"` format for additional configuration. **Examples:** **1. Create a property list for PII data.** ``` Invoke-Command -ComputerName $FSxWindowsRemotePowerShellEndpoint -ConfigurationName FSxRemoteAdmin -ScriptBlock { New-FSxFSRMClassificationPropertyDefinition -Name "ContainsPII" -Type OrderedList -PossibleValueConfigurations @( @{ Name = "Yes" }, @{ Name = "No" }) } ``` **2. Create an ordered list property for Data Sensitivity.** ``` Invoke-Command -ComputerName $FSxWindowsRemotePowerShellEndpoint -ConfigurationName FSxRemoteAdmin -ScriptBlock { New-FSxFSRMClassificationPropertyDefinition -Name "DataSensitivity" -Type OrderedList -PossibleValueConfigurations @( @{ Name = "Public" }, @{ Name = "Internal" }, @{ Name = "Confidential" }, @{ Name = "Restricted" } ) } ``` #### Get-FSxFSRMClassificationPropertyDefinition Get-FSxFSRMClassificationPropertyDefinition `Get-FSxFSRMClassificationPropertyDefinition`: Retrieves one or more classification property definitions from your file system. **Parameters:** + `Name (array)` - Optional. An array of names of property definitions to retrieve. If you don't specify a name, the command returns all property definitions on the file system. **Examples:** **1. Retrieve all classification property definitions on the file system.** ``` Invoke-Command -ComputerName $FSxWindowsRemotePowerShellEndpoint -ConfigurationName FSxRemoteAdmin -ScriptBlock { Get-FSxFSRMClassificationPropertyDefinition } ``` #### Set-FSxFSRMClassificationPropertyDefinition Set Property Definition Modifies the properties of an existing classification property definition. ##### Parameters Parameters + `Name (array)` - Required. An array of property names to modify. + `DisplayName (string)` - Optional. A new display name for the property definition. + `Description (string)` - Optional. A new description for the property definition. + `PossibleValueConfigurations (array)` - Optional. A new array of configurations for OrderedList, MultiChoice, or SingleChoice properties. Each configuration has the following properties: + `Name (string)`: The name of the value (required) + `Description (string)`: A description of the value (optional) + `Parameters (array)` - Optional. A new array of strings in "name=value" format. + `PassThru (boolean)` - Optional. If set to true, returns the modified property definition object. **Examples:** 1. Update possible values with descriptions on an existing Property Definition. ``` $values = [System.Collections.ArrayList]@() $null = $values.Add(@{ Name = "High" Description = "High Risk Content" }) $null = $values.Add(@{ Name = "Medium" Description = "Medium Risk Content" }) Invoke-Command -ComputerName $FSxWindowsRemotePowerShellEndpoint -ConfigurationName FSxRemoteAdmin -ArgumentList $values -ScriptBlock { param($values) Set-FSxFSRMClassificationPropertyDefinition -Name "RiskLevel" -PossibleValueConfigurations $Using:values -PassThru } ``` #### Remove-FSxFSRMClassificationPropertyDefinition Remove Property Definition Removes one or more classification property definitions from your file system. Only locally defined property definitions can be removed. ##### Parameters Parameters + `Name (array)` - Required. An array of property names to remove. + `PassThru (boolean)` - Optional. If set to true, returns the removed property definition object. **Examples:** 1. Remove a single property definition. ``` Invoke-Command -ComputerName $FSxWindowsRemotePowerShellEndpoint -ConfigurationName FSxRemoteAdmin -ScriptBlock { Remove-FSxFSRMClassificationPropertyDefinition -Name "RiskLevel" -PassThru } ``` ### Classification Rule Commands Classification Rules #### New-FSxFSRMClassificationRule New Classification Rule Creates an automatic classification rule that assigns property values to files based on specified criteria. Each rule sets a value for a single property. ##### Parameters Parameters + `Name (string)` - Required. A name for the classification rule. + `Description (string)` - Optional. A description for the classification rule. + `Property (string)` - Required. The name of the classification property to set. Must be an existing property definition name. + `PropertyValue (string)` - Optional. The value to assign to the property. Must be valid for the specified classification mechanism. + `Namespace (array)` - Required. An array of paths or folder types where the rule applies. + `Disabled (boolean)` - Optional. If set to true, creates the rule in a disabled state. + `ReevaluateProperty (string)` - Optional. Specifies when to re-evaluate files. You can specify the following values: + `Never`: Only evaluate files without existing property value + `Overwrite`: Re-evaluate when files change and overwrite existing value + `Aggregate`: Re-evaluate when files change and combine with existing value + `Flags (array)` - Optional. Specifies special behaviors for the rule. You can specify the following values: + `ClearAutomaticallyClassifiedProperty` + `ClearManuallyClassifiedProperty` + `Deprecated` + `ContentRegularExpression (array)` - Optional. An array of regular expressions to match file content. + `ContentString (array)` - Optional. An array of case-insensitive strings to search for in file content. + `ClassificationMechanism (string)` - Required. The mechanism to use for classifying files. You can specify the following values: + `Content Classifier`: Scans file content for specific strings or regular expression patterns. When you specify Content Classifier, you can use the ContentString, ContentStringCaseSensitive, or ContentRegularExpression parameters to define the content to search for. + `Folder Classifier`: Classifies files based on their folder location + `Parameters (array)` - Optional. An array of `"name=value"` strings for additional configuration. **Examples:** 1. Detect Social Security Numbers using a Regular Expression. ``` Invoke-Command -ComputerName $FSxWindowsRemotePowerShellEndpoint -ConfigurationName FSxRemoteAdmin -ScriptBlock { New-FSxFSRMClassificationRule -Name "Detect_SSN" -Property "ContainsPII" -PropertyValue "Yes" -Namespace "share" -ClassificationMechanism "Content Classifier" -ContentRegularExpression "\b\d{3}-\d{2}-\d{4}\b" } ``` 2. Detect Credit Card Numbers using a regular Expression. ``` Invoke-Command -ComputerName $FSxWindowsRemotePowerShellEndpoint -ConfigurationName FSxRemoteAdmin -ScriptBlock { New-FSxFSRMClassificationRule -Name "Detect_CreditCard" -Property "ContainsPII" -PropertyValue "Yes" -Namespace "share" -ClassificationMechanism "Content Classifier" -ContentRegularExpression "\b\d{4}[\s-]?\d{4}[\s-]?\d{4}[\s-]?\d{4}\b" } ``` 3. Classify every file under a folder with a 7-year retention period Property. ``` Invoke-Command -ComputerName $FSxWindowsRemotePowerShellEndpoint -ConfigurationName FSxRemoteAdmin -ScriptBlock { New-FSxFSRMClassificationRule -Name "Contracts_Records_7Year" -Property "RetentionPeriod" -PropertyValue "7 years" -Namespace "share/Legal Documents" -ClassificationMechanism "Folder Classifier" } ``` #### Get-FSxFSRMClassificationRule Get Classification Rule Retrieves one or more classification rules from your file system. ##### Parameters Parameters + `Name (array)` - Optional. An array of names of classification rules to retrieve. If you don't specify a name, the command returns all rules on the file system. **Examples:** 1. Retrieve all classification rules on the file system. ``` Invoke-Command -ComputerName $FSxWindowsRemotePowerShellEndpoint -ConfigurationName FSxRemoteAdmin -ScriptBlock { Get-FSxFSRMClassificationRule } ``` ##### Set-FSxFSRMClassificationRule Set-FSxFSRMClassificationRule Modifies the properties of existing classification rules. ##### Parameters Parameters + `Name (array)` - Required. An array of names of classification rules to modify. + `Description (string)` - Optional. A new description for the rule. + `Property (string)` - Optional. The name of the classification property to set. + `PropertyValue (string)` - Optional. A new value to assign to the property. + `Namespace (array)` - Optional. A new array of paths or folder types where the rule applies. + `Disabled (boolean)` - Optional. If set to true, disables the rule. If set to false, enables the rule. + `ReevaluateProperty (string)` - Optional. Changes when to re-evaluate files. You can specify the following values: + `Never`: Only evaluate files without existing property value + `Overwrite`: Re-evaluate when files change and overwrite existing value + `Aggregate`: Re-evaluate when files change and combine with existing value + `Flags (array)` - Optional. New special behaviors for the rule. You can specify the following values: + `ClearAutomaticallyClassifiedProperty` + `ClearManuallyClassifiedProperty` + `Deprecated` + `ContentRegularExpression (array)` - Optional. A new array of regular expressions. + `ContentString (array)` - Optional. A new array of case-insensitive search strings. + `ContentStringCaseSensitive (array)` - Optional. A new array of case-sensitive search strings. + `ClassificationMechanism (string)` - Optional. A new classification mechanism to use. You can specify the following values: + `Content Classifier`: Scans file content for specific strings or regular expression patterns. When you specify Content Classifier, you can use the ContentString, ContentStringCaseSensitive, or ContentRegularExpression parameters to define the content to search for. + `Folder Classifier`: Classifies files based on their folder location + `Parameters (array)` - Optional. A new array of `"name=value"` configuration strings. + `PassThru (boolean)` - Optional. If set to true, returns the modified rule object. **Examples:** 1. Update rule properties and namespace of an existing Classification Rule. ``` $namespaces = @("share\finance", "share\accounting") Invoke-Command -ComputerName $FSxWindowsRemotePowerShellEndpoint -ConfigurationName FSxRemoteAdmin -ArgumentList $namespaces -ScriptBlock { param($namespaces) Set-FSxFSRMClassificationRule -Name "Detect_CreditCard" -Description "Updated PII detection" -Namespace $Using:namespaces -ReevaluateProperty "Overwrite" } ``` ##### Remove-FSxFSRMClassificationRule Remove-FSxFSRMClassificationRule Removes one or more classification rules from your file system. ##### Parameters Parameters + `Name (array)` - Required. An array of names of classification rules to remove. + `PassThru (boolean)` - Optional. If set to true, returns the removed rule object. **Examples:** 1. Remove a single classification rule. ``` Invoke-Command -ComputerName $FSxWindowsRemotePowerShellEndpoint -ConfigurationName FSxRemoteAdmin -ScriptBlock { Remove-FSxFSRMClassificationRule -Name "Find Confidential Files" -PassThru } ``` ### Management Property Commands Management Property Commands #### Get-FSxFSRMMgmtProperty Get-FSxFSRMMgmtProperty Retrieves management properties from specified folders. Management properties are classification properties that apply to folders rather than files. ##### Parameters Parameters + `Namespace (string)` - Optional. A path to a folder. + `Name (string)` - Optional. The name of a management property to retrieve. If you don't specify a name, the command retrieves all management properties. + `Recurse (boolean)` - Optional. If set to true, retrieves management properties for all folders within the namespace. Requires the Namespace parameter. + `Effective (boolean)` - Optional. If set to true, retrieves the management property for the nearest folder with the specified name. The search includes the specified namespace and its parent hierarchy. Requires the Name parameter. **Examples:** 1. Retrieve all management properties on the file system. ``` Invoke-Command -ComputerName $FSxWindowsRemotePowerShellEndpoint -ConfigurationName FSxRemoteAdmin -ScriptBlock { Get-FSxFSRMMgmtProperty } ``` 2. Retrieve management properties for a specific folder. ``` Invoke-Command -ComputerName $FSxWindowsRemotePowerShellEndpoint -ConfigurationName FSxRemoteAdmin -ScriptBlock { Get-FSxFSRMMgmtProperty -Namespace "share\department" } ``` #### Remove-FSxFSRMMgmtProperty Remove-FSxFSRMMgmtProperty Removes management properties from specified folders. ##### Parameters Parameters + `Namespace (string)` - Optional. A path to a folder. + `Name (string)` - Required. The name of the management property to remove. + `Recurse (boolean)` - Optional. If set to true, removes management properties for all folders within the namespace. Requires the Namespace parameter. **Examples:** 1. Remove all instances of a management property. ``` Invoke-Command -ComputerName $FSxWindowsRemotePowerShellEndpoint -ConfigurationName FSxRemoteAdmin -ScriptBlock { Remove-FSxFSRMMgmtProperty -Name "FolderUsage_MS" } ``` 2. Remove a management property from a specific folder. ``` Invoke-Command -ComputerName $FSxWindowsRemotePowerShellEndpoint -ConfigurationName FSxRemoteAdmin -ScriptBlock { Remove-FSxFSRMMgmtProperty -Name "FolderUsage_MS" -Namespace "share\department" } ``` #### Set-FSxFSRMMgmtProperty Set-FSxFSRMMgmtProperty Changes the value of a management property for a specified namespace. Management properties are classification properties that apply to folders and don't have the Secure flag set. ##### Parameters Parameters + `Namespace (string)` - Optional. The folder path. + `Name (string)` - Required. The name of the management property to modify. Must be an existing classification property that applies to folders. + `Value (string)` - Required. The new value to assign to the management property. **Examples:** 1. Set a folder usage property. ``` Invoke-Command -ComputerName $FSxWindowsRemotePowerShellEndpoint -ConfigurationName FSxRemoteAdmin -ScriptBlock { Set-FSxFSRMMgmtProperty -Namespace "share\department" -Name "FolderUsage_MS" -Value "User Files" } ``` ### Classification Process Commands Classification Process Commands #### Get-FSxFSRMClassification Get-FSxFSRMClassification Retrieves the status of the running file classification process. The status can be one of the following values: + `Unknown`: The classification status cannot be determined + `NotRunning`: No classification is currently running + `Queued`: Classification is queued to start + `Running`: Classification is currently in progress ##### Parameters Parameters None **Examples:** 1. Retrieve the current classification status. ``` Invoke-Command -ComputerName $FSxWindowsRemotePowerShellEndpoint -ConfigurationName FSxRemoteAdmin -ScriptBlock { Get-FSxFSRMClassification } ``` #### Start-FSxFSRMClassification Start-FSxFSRMClassification Initiates the file classification process, which applies classification rules to files and generates a classification report. ##### Parameters Parameters + `Queue (boolean)` - Optional. If set to true, adds the classification task to a queue to run within the next 5 minutes. Any tasks queued during this period will run together. If set to false or not specified, classification starts immediately. + `RunDuration (number)` - Optional. Specifies how many hours the classification process should run before being canceled. Valid values: `-1` to `2147483`. Special values: + `-1`: Run until canceled + `0`: Run to completion + If not specified, runs to completion. **Examples:** 1. Start classification with no time limit. ``` Invoke-Command -ComputerName $FSxWindowsRemotePowerShellEndpoint -ConfigurationName FSxRemoteAdmin -ScriptBlock { Start-FSxFSRMClassification -RunDuration 0 } ``` #### Stop-FSxFSRMClassification Stop-FSxFSRMClassification Stops any running or queued classification job on your file system. ##### Parameters Parameters None **Examples:** 1. Stop a running classification. ``` Invoke-Command -ComputerName $FSxWindowsRemotePowerShellEndpoint -ConfigurationName FSxRemoteAdmin -ScriptBlock { Stop-FSxFSRMClassification } ``` #### Wait-FSxFSRMClassification Wait-FSxFSRMClassification Waits for the file classification process to complete. Use this command when you need to perform actions that depend on classification finishing, such as generating reports based on classified files. ##### Parameters Parameters + `Timeout (number)` - Optional. Specifies how long to wait, in seconds, for the classification to complete. If the timeout expires before classification finishes, the command returns but classification continues running in the background. Valid values: `-1` to `2147483`. Special values: + `-1`: Wait indefinitely until classification completes (default) + `0`: Check the current status and return immediately without waiting **Examples:** 1. Wait indefinitely for classification to complete. ``` Invoke-Command -ComputerName $FSxWindowsRemotePowerShellEndpoint -ConfigurationName FSxRemoteAdmin -ScriptBlock { Wait-FSxFSRMClassification } ``` #### Set-FSxFSRMClassification Set-FSxFSRMClassification Modifies the configuration settings for file classification. ##### Parameters Parameters + `ExcludeNamespace (array)` - Optional. An array of additional folders to exclude from classification. + `ScheduleConfigurations (hashtable)` - Optional. A hashtable containing schedule configuration with the following properties: + `Time (datetime)`: DateTime object specifying when to run the task (required) + `RunDuration (number)`: Number of hours to run the task (optional) + `Weekly (array)`: Array of weekdays (optional) + `Monthly (array)`: Array of days of month, use -1 for last day (optional) + `Continuous (boolean)` - Optional. If set to true, enables continuous background classification. + `PassThru (boolean)` - Optional. If set to true, returns the modified classification configuration object. **Examples:** 1. Enable continuous classification. ``` Invoke-Command -ComputerName $FSxWindowsRemotePowerShellEndpoint -ConfigurationName FSxRemoteAdmin -ScriptBlock { Set-FSxFSRMClassification -Continuous $true } ``` 2. Set a weekly schedule to run classification. ``` $schedule = @{ Time = ("12:00am") Weekly = @('Monday', 'Wednesday', 'Friday') } Invoke-Command -ComputerName $FSxWindowsRemotePowerShellEndpoint -ConfigurationName FSxRemoteAdmin -ArgumentList $schedule -ScriptBlock { param($schedule) Set-FSxFSRMClassification -ScheduleConfigurations $schedule } ``` 3. Set a monthly schedule with custom exclusions. ``` $schedule = @{ Time = ("12:00am") Monthly = @(1, 15, -1) # 1st, 15th, and last day RunDuration = 4 } $excludeNamespaces = @("share\folder /s") Invoke-Command -ComputerName $FSxWindowsRemotePowerShellEndpoint -ConfigurationName FSxRemoteAdmin -ArgumentList @($schedule, $excludeNamespaces) -ScriptBlock { param($schedule, $excludeNamespaces) Set-FSxFSRMClassification -ScheduleConfigurations $schedule -ExcludeNamespace $excludeNamespaces } ``` # Storage Reports Storage Reports Storage reports provide detailed analysis of file system usage, helping you understand how storage is being consumed, identify files that can be archived or deleted, and monitor compliance with file management policies. You can generate multiple types of reports that analyze file ownership, file types, duplicate files, large files, file screening and quota usage. ## Report types Report types You can create the following report types: + `DuplicateFiles` Identifies files that have identical content based on file size and hash comparison. Use this report to find redundant files that consume unnecessary storage space. The report groups duplicate files together and shows the total space that could be recovered by removing duplicates. + `FilesByFileGroup` Groups files by their [file group](fsrm-file-groups.md) membership and shows storage consumption for each file group. Use this report to understand which types of files (documents, media, executables, etc.) consume the most storage space. + `FilesByOwner` Groups files by owner and shows how much storage each user or group consumes. Use this report to identify users who are consuming the most storage space and to allocate storage costs or quotas appropriately. + `FilesByProperty` Groups files by classification property values and shows file count and storage consumption for each property value. Use this report to analyze files based on their classification, such as data sensitivity level, department, or retention period. This report requires that files have been classified using [Classification rules](fsrm-file-classification.md#fsrm-classification-rules). + `FileScreenAuditFiles` Lists [File Screening](fsrm-file-screening.md) violations where users attempted to save files that were blocked by active file screens. Use this report to monitor compliance with file screening policies and identify users who frequently attempt to save unauthorized file types. + `FoldersByProperty` Groups folders by management property values and shows storage consumption for each property value. Use this report to analyze storage usage by folder purpose, such as user files, group shares, or application files. + `LargeFiles` Lists files that exceed a specified size threshold. Use this report to identify files that consume significant storage space and may be candidates for archiving, compression, or deletion. + `LeastRecentlyAccessed` Lists files that haven't been accessed for a specified number of days. Use this report to identify inactive files that can be archived or moved to lower-cost storage tiers. + `MostRecentlyAccessed` Lists files that were accessed within a specified number of days. + `QuotaUsage` Shows quota usage statistics for folders with [quotas](fsrm-quota-management.md) configured. Use this report to monitor quota compliance and identify folders approaching their quota limits. ## Report formats Report formats You can generate reports in multiple formats to suit different use cases: + `DHTML` - Dynamic HTML format with interactive features like sorting and filtering. + `HTML` - Static HTML format suitable for archiving or emailing. + `XML` - Structured data format for programmatic processing. + `CSV` - Comma-separated values format for importing into spreadsheet applications. + `Text` - Plain text format for simple viewing or processing. You can specify multiple formats for a single report. ## Interactive and scheduled reports Interactive and scheduled reports You can create two types of storage reports: 1. **Interactive reports** - Run immediately when created and execute only once. Use interactive reports for ad-hoc analysis or troubleshooting. Interactive reports do not have schedules and cannot be modified after creation. To run another interactive report, you must create a new report with a different name. 1. **Scheduled reports** - Run automatically according to a configured schedule. Use scheduled reports for regular monitoring and compliance reporting. You can schedule reports to run weekly or monthly at specific times. Scheduled reports can be modified to change their configuration, and you can also run them on-demand using the [Start-FSxFSRMStorageReport](#start-fsxfsrmstoragereport) command without waiting for the scheduled time. ## Running reports Running reports After you create a scheduled report, you can run it in several ways: + **Automatic execution** - Scheduled reports run automatically at their configured schedule time. + **Manual execution** - Use [Start-FSxFSRMStorageReport](#start-fsxfsrmstoragereport) to run a scheduled report on-demand without waiting for the scheduled time. You can monitor report execution using [Get-FSxFSRMStorageReport](#get-fsxfsrmstoragereport) to check the status. ## Accessing storage reports Accessing storage reports After FSRM generates storage reports, the report files are saved to a default location on your file system. To access these reports, you need to map the administrative D\$1 share of your file system. **To access storage reports** 1. Map the administrative D\$1 share using the following path format: ``` \\file-system-dns-name\D$ ``` For example: ``` \\amznfsxaa11bb22.corp.example.com\D$ ``` 1. Navigate to the StorageReports folder. This folder contains subfolders organized by report type and execution date. **Note** Accessing the administrative D\$1 share requires administrator credentials. ## Storage report best practices Best practices Follow these best practices to ensure efficient and effective storage reporting: ### Performance considerations Performance considerations Storage report generation is resource-intensive because FSRM must scan large amounts of files. + **Limit report scope** - Use the `Namespace` parameter to limit reports to specific folders rather than scanning the entire file system. Scanning large directory structures is resource-intensive and can take hours to complete. + **Schedule reports during off-peak hours** - Run scheduled reports during periods of low system activity, to minimize impact on performance. Avoid running reports during backup windows or other maintenance tasks. + **Set reasonable thresholds** - Use threshold parameters to limit report output to actionable data. For example, set `LargeFileMinimum` to a value that identifies files worth investigating, not every file over 1MB. + **Use RunDuration limits** - Set the `RunDuration` parameter to prevent reports from running too long and impacting system performance. If a report doesn't complete within the time limit, it will resume during the next scheduled run. + **Monitor report performance** - Use [Get-FSxFSRMStorageReport](#get-fsxfsrmstoragereport) to check how long reports take to complete. If reports consistently take too long, consider narrowing their scope or running them less frequently. ### Report design Report design + **Use descriptive names** - Give reports clear, descriptive names that indicate what they analyze and when they run, such as "Weekly Large Files - Finance Share" or "Monthly Duplicate Files - All Shares". + **Combine related analysis** - When generating multiple report types for the same namespace, create a single report with multiple `ReportType` values rather than separate reports. This is more efficient because FSRM only needs to scan the directory structure once. + **Filter by file patterns** - Use file pattern parameters to focus reports on specific file types. For example, when analyzing large files, you might create separate reports for video files, database files, and archive files to better understand storage consumption patterns. + **Leverage classification properties** - Use `FilesByProperty` reports to analyze files based on their classification. This provides more meaningful insights. ### Report management Report management + **Review reports regularly** - Schedule time to review report results and take action on findings. Reports are only valuable if you use them to make storage management decisions. + **Archive old reports** - Report files accumulate over time and consume storage space. Establish a retention policy for report files and delete or archive old reports that are no longer needed. + **Test reports before scheduling** - Create interactive reports to test report configurations and verify they produce the expected results before creating scheduled versions. ## Storage report management commands Management commands You can access two families of FSx remote PowerShell commands for managing storage reports: 1. **Report definition commands** - Create, retrieve, modify, and remove storage report configurations that specify what data to analyze, when to run reports, and what formats to generate. 1. **Report execution commands** - Start, stop, monitor, and wait for storage report generation. Use these commands to run reports on-demand or manage long-running report jobs. ### List of Storage Report FSx remote PowerShell commands PowerShell Commands **Note** All the examples in this page assume that you have defined the ` $FSxWindowsRemotePowerShellEndpoint` variable with your file system's Windows Remote PowerShell endpoint. You can find this endpoint in the Amazon FSx console on your file system's details page, or by using the AWS CLI `describe-file-systems` command. ### Report Definition Commands Definition Commands #### New-FSxFSRMStorageReport New-FSxFSRMStorageReport **New-FSxFSRMStorageReport**: Creates a storage report that analyzes specified directories to generate one or more report types. **Parameters:** + `Name (string)` - Required. A name for the storage report. + `Namespace (array)` - Required. An array of paths or folder types to analyze. You can specify paths in multiple formats: + Folder Path + [Folder classification](fsrm-file-classification.md#fsrm-management-properties). For example, [FolderUsage\$1MS="User Files"] + `ReportType (array)` - Required. An array of report types to generate. You can specify the following values: + `DuplicateFiles`: Identifies duplicate files based on file size and content + `FilesByFileGroup`: Groups files by file group membership + `FilesByOwner`: Groups files by owner + `FilesByProperty`: Groups files by classification property + `FileScreenAuditFiles`: Lists file screening violations + `FoldersByProperty`: Groups folders by management property + `LargeFiles`: Lists files above a specified size threshold + `LeastRecentlyAccessed`: Lists files that haven't been accessed recently + `MostRecentlyAccessed`: Lists files that were accessed recently + `QuotaUsage`: Shows quota usage statistics + `ReportFormat (array)` - Optional. An array of output formats. You can specify the following values: + `DHTML`: Dynamic HTML format + `HTML`: Static HTML format + `XML`: XML format + `CSV`: Comma-separated values format + `Text`: Plain text format + `Interactive (boolean)` - Optional. If set to true, generates an interactive report. Interactive reports cannot be modified after creation. + `ScheduleConfigurations (hashtable)` - Required unless report is Interactive. A hashtable containing schedule configuration with the following properties: + `Time (datetime)`: DateTime object specifying when to run the task (required) + `RunDuration (number)`: Number of hours to run the task (optional) + `Weekly (array)`: Array of weekdays (optional) + `Monthly (array)`: Array of days of month, use `-1` for last day (optional) **Report-specific parameters:** + `FileScreenAuditDaysSince (number)` - Optional. For FileScreenAuditFiles reports, specifies how many days back to include audit events. + `FileScreenAuditUser (array)` - Optional. For FileScreenAuditFiles reports, specifies an array of user accounts to include in the report. Only file screening violations by these users will be included. + `FileGroupIncluded (array)` - Optional. For FilesByFileGroup reports, specifies which file groups to include. + `FileOwnerFilePattern (string)` - Optional. For FilesByOwner reports, specifies a file pattern to filter results. + `PropertyName (string)` - Optional. For FilesByProperty reports, specifies the classification property to group by. + `FolderPropertyName (string)` - Optional. For FoldersByProperty reports, specifies the folder property to group by. + `PropertyFilePattern (string)` - Optional. For FilesByProperty and FoldersByProperty, specifies a file pattern to filter results. + `LargeFileMinimum (number)` - Optional. For LargeFiles reports, specifies the minimum file size in bytes. + `LargeFilePattern (string)` - Optional. For LargeFiles reports, specifies a file pattern to filter results. + `LeastAccessedMinimum (number)` - Optional. For LeastRecentlyAccessed reports, specifies the minimum number of days since last access. + `LeastAccessedFilePattern (string)` - Optional. For LeastRecentlyAccessed reports, specifies a file pattern to filter results. + `MostAccessedMaximum (number)` - Optional. For MostRecentlyAccessed reports, specifies the maximum number of days since last access. + `MostAccessedFilePattern (string)` - Optional. For MostRecentlyAccessed reports, specifies a file pattern to filter results. + `QuotaMinimumUsage (number)` - Optional. For QuotaUsage reports, specifies the minimum quota usage percentage to include. **Examples:** 1. Create a monthly large files report. ``` $schedule = @{ Time = ("3:00 AM") Monthly = @(1) # Run on first day } Invoke-Command -ComputerName $FSxWindowsRemotePowerShellEndpoint -ConfigurationName FSxRemoteAdmin -ArgumentList $schedule -ScriptBlock { param($schedule) New-FSxFSRMStorageReport -Name "Monthly Large Files" -Namespace "share\data" -ReportType "LargeFiles" -LargeFileMinimum 100MB -ReportFormat "HTML" -ScheduleConfigurations $schedule } ``` 2. Create a weekly duplicate files report with multiple namespaces and formats. ``` $schedule = @{ Time = ("12:00 AM") Weekly = @('Sunday') RunDuration = 4 } $namespaces = @("share\docs", "[FolderUsage_MS=User Files]") $reportFormats = @("HTML", "CSV") Invoke-Command -ComputerName $FSxWindowsRemotePowerShellEndpoint -ConfigurationName FSxRemoteAdmin -ArgumentList @($schedule, $namespaces, $reportFormats) -ScriptBlock { param($schedule, $namespaces, $reportFormats) New-FSxFSRMStorageReport -Name "Weekly Duplicates" -Namespace $namespaces -ReportType "DuplicateFiles" -ReportFormat $reportFormats -ScheduleConfigurations $schedule } ``` 3. Create an interactive report that runs immediately. ``` Invoke-Command -ComputerName $FSxWindowsRemotePowerShellEndpoint -ConfigurationName FSxRemoteAdmin -ScriptBlock { New-FSxFSRMStorageReport -Name "Find large files" -Namespace "share" -Interactive $true -ReportType "QuotaUsage" } ``` #### Get-FSxFSRMStorageReport Get-FSxFSRMStorageReport **Get-FSxFSRMStorageReport**: Retrieves one or more storage reports from your file system. Returns details about report configurations and status. **Parameters:** + `Name (array)` - Optional. An array of report names to retrieve. If you don't specify a name, the command returns all storage reports on the file system. **Examples:** 1. Retrieve all storage reports on the file system. ``` Invoke-Command -ComputerName $FSxWindowsRemotePowerShellEndpoint -ConfigurationName FSxRemoteAdmin -ScriptBlock { Get-FSxFSRMStorageReport } ``` #### Remove-FSxFSRMStorageReport Remove-FSxFSRMStorageReport **Remove-FSxFSRMStorageReport**: Removes one or more storage reports from your file system. You cannot remove reports that are currently running. **Parameters:** + `Name (array)` - Required. An array of report names to remove. + `PassThru (boolean)` - Optional. If set to true, returns the removed report object. **Examples:** 1. Remove a single storage report. ``` Invoke-Command -ComputerName $FSxWindowsRemotePowerShellEndpoint -ConfigurationName FSxRemoteAdmin -ScriptBlock { Remove-FSxFSRMStorageReport -Name "Monthly Report" -PassThru } ``` #### Set-FSxFSRMStorageReport Modify Storage Reports ##### Parameters Parameters + `Name (array)` - Required. An array of report names to modify. + `Namespace (array)` - Optional. An array of paths or folder types to analyze. You can specify paths in multiple formats: + Folder Path + [Folder classification](fsrm-file-classification.md#fsrm-management-properties). For example, [FolderUsage\$1MS="User Files"] + `ReportType (array)` - Optional. An array of report types to generate. You can specify the following values: + `DuplicateFiles`: Identifies duplicate files based on file size and content + `FilesByFileGroup`: Groups files by file group membership + `FilesByOwner`: Groups files by owner + `FilesByProperty`: Groups files by classification property + `FileScreenAuditFiles`: Lists file screening violations + `FoldersByProperty`: Groups folders by management property + `LargeFiles`: Lists files above a specified size threshold + `LeastRecentlyAccessed`: Lists files that haven't been accessed recently + `MostRecentlyAccessed`: Lists files that were accessed recently + `QuotaUsage`: Shows quota usage statistics + `ReportFormat (array)` - Optional. An array of output formats. You can specify the following values: + `DHTML`: Dynamic HTML format + `HTML`: Static HTML format + `XML`: XML format + `CSV`: Comma-separated values format + `Text`: Plain text format + `ScheduleConfigurations (hashtable)` - Required unless report is Interactive. A hashtable containing schedule configuration with the following properties: + `Time (datetime)`: DateTime object specifying when to run the task (required) + `RunDuration (number)`: Number of hours to run the task (optional) + `Weekly (array)`: Array of weekdays (optional) + `Monthly (array)`: Array of days of month, use `-1` for last day (optional) + `PassThru (boolean)` - Optional. If set to true, returns the modified report object. ##### Report-Specific Parameters Report Parameters + `FileScreenAuditDaysSince (number)` - Optional. For FileScreenAuditFiles reports, specifies how many days back to include audit events. + `FileScreenAuditUser (array)` - Optional. For FileScreenAuditFiles reports, specifies an array of user accounts to include in the report. Only file screening violations by these users will be included. + `FileGroupIncluded (array)` - Optional. For FilesByFileGroup reports, specifies which file groups to include. + `FileOwnerFilePattern (string)` - Optional. For FilesByOwner reports, specifies a file pattern to filter results. + `PropertyName (string)` - Optional. For FilesByProperty reports, specifies the classification property to group by. + `FolderPropertyName (string)` - Optional. For FoldersByProperty reports, specifies the folder property to group by. + `PropertyFilePattern (string)` - Optional. For FilesByProperty and FoldersByProperty, specifies a file pattern to filter results. + `LargeFileMinimum (number)` - Optional. For LargeFiles reports, specifies the minimum file size in bytes. + `LargeFilePattern (string)` - Optional. For LargeFiles reports, specifies a file pattern to filter results. + `LeastAccessedMinimum (number)` - Optional. For LeastRecentlyAccessed reports, specifies the minimum number of days since last access. + `LeastAccessedFilePattern (string)` - Optional. For LeastRecentlyAccessed reports, specifies a file pattern to filter results. + `MostAccessedMaximum (number)` - Optional. For MostRecentlyAccessed reports, specifies the maximum number of days since last access. + `MostAccessedFilePattern (string)` - Optional. For MostRecentlyAccessed reports, specifies a file pattern to filter results. + `QuotaMinimumUsage (number)` - Optional. For QuotaUsage reports, specifies the minimum quota usage percentage to include. ##### Examples: Example 1. Update schedule and format for an existing report. ``` $schedule = @{ Time = ("3:00 AM") Monthly = @(1) } $reportFormats = @("HTML", "CSV") Invoke-Command -ComputerName $FSxWindowsRemotePowerShellEndpoint -ConfigurationName FSxRemoteAdmin -ArgumentList @($schedule, $reportFormats) -ScriptBlock { param($schedule, $reportFormats) Set-FSxFSRMStorageReport -Name "Monthly Report" -ScheduleConfigurations $schedule -ReportFormat $reportFormats -PassThru } ``` ### Report Execution Commands Report Execution #### Start-FSxFSRMStorageReport Start Reports ##### Parameters Parameters + `Name (array)` - Required. An array of report names to start. + `Queue (boolean)` - Optional. If set to true, adds the report to a queue to run within the next 5 minutes. Any reports queued during this period will run together. If set to false or not specified, the report starts immediately. + `RunDuration (number)` - Optional. Specifies how many hours the report should run before being canceled. Valid values: `-1` to `2147483`. Special values: + `0`: Run to completion + `-1`: Run until canceled If not specified, runs to completion. ##### Examples Examples 1. Start a storage report immediately. ``` Invoke-Command -ComputerName $FSxWindowsRemotePowerShellEndpoint -ConfigurationName FSxRemoteAdmin -ScriptBlock { Start-FSxFSRMStorageReport -Name "Monthly Report" } ``` 2. Queue a storage report with a duration limit. ``` Invoke-Command -ComputerName $FSxWindowsRemotePowerShellEndpoint -ConfigurationName FSxRemoteAdmin -ScriptBlock { Start-FSxFSRMStorageReport -Name "Quarterly Report" -Queue: $true -RunDuration 4 } ``` #### Stop-FSxFSRMStorageReport Stop Reports ##### Parameters Parameters + `Name (array)` - Required. An array of report names to stop. ##### Examples: Example 1. Stop a single storage report. ``` Invoke-Command -ComputerName $FSxWindowsRemotePowerShellEndpoint -ConfigurationName FSxRemoteAdmin -ScriptBlock { Stop-FSxFSRMStorageReport -Name "Monthly Report" } ``` #### Wait-FSxFSRMStorageReport Wait for Reports ##### Parameters Parameters + `Name (array)` - Required. An array of report names to wait for. + `Timeout (number)` - Optional. Specifies how long to wait, in seconds, for the reports to complete. If the timeout expires before reports finish, the command returns but report generation continues running in the background. Valid values: `-1` to `2147483`. Special values: + `-1`: Wait indefinitely until reports complete (default) + `0`: Check the current status and return immediately without waiting ##### Examples: Example 1. Wait indefinitely for a storage report to complete. ``` Invoke-Command -ComputerName $FSxWindowsRemotePowerShellEndpoint -ConfigurationName FSxRemoteAdmin -ScriptBlock { Wait-FSxFSRMStorageReport -Name "Monthly Report" } ``` # File Management Tasks File Management Tasks Amazon FSx for Windows File Server does not support FSRM file management tasks. However, you can achieve common use cases such as data archiving and retention policies by using native PowerShell commands from client machines that have network access to your file system. For example, you can use PowerShell scripts on client machines to: + Move or archive files based on age or last access time + Delete classified files that exceed a retention period + Copy files to archive storage based on classification properties You can access files properties using the `Get-FsrmClassification` command and take actions based on the values. To access FSRM classification properties or other FSRM metadata from client-side PowerShell scripts, the client machine must also have FSRM installed. # FSRM Settings FSRM Settings FSRM settings provide system-wide configuration that allows you to customize behavior and streamline feature management. Use these settings to control how FSRM operates across your file system and to set default values that simplify creating and configuring features like storage reports and file screening. ## Settings categories Settings categories FSRM settings are organized into three categories: ### File screen auditing File screen auditing File screen auditing records when users attempt to save files that are blocked by active file screens. This information is essential for monitoring compliance with file screening policies and identifying users who frequently attempt to save unauthorized file types. + `ReportFileScreenAuditEnable` - This setting controls whether FSRM logs file screening violations at all. If disabled, FSRM does not record file screen violations, and `FileScreenAuditFiles` reports will have no data to display. You must enable this setting to use file screen audit reports. + `ReportFileScreenAuditDaysSince` - This setting provides the default time range for file screen audit reports. When you create a `FileScreenAuditFiles` report without specifying how far back to look, FSRM uses this value. Setting an appropriate default (such as 30 days) ensures that reports focus on recent violations without including excessive historical data. + `ReportFileScreenAuditUser` - This setting provides the default list of users to include in file screen audit reports. When you create a `FileScreenAuditFiles` report without specifying which users to include, FSRM uses this list. If empty, reports include all users by default. You can use this setting to focus reports on specific user groups or departments. ### Default report filters Default report filters Default report filter settings provide values that are used when you create storage reports without specifying certain parameters. These defaults simplify report creation and ensure consistency across similar reports. Each report type has associated default settings: + Large file reports - `ReportLargeFileMinimum` sets the default minimum file size, and `ReportLargeFilePattern` sets the default file pattern filter. + Least accessed file reports - `ReportLeastAccessedMinimum` sets the default number of days since last access, and `ReportLeastAccessedFilePattern` sets the default file pattern filter. + Most accessed file reports - `ReportMostAccessedMaximum` sets the default maximum number of days since last access, and `ReportMostAccessedFilePattern` sets the default file pattern filter. + Files by owner reports - `ReportFileOwnerFilePattern` sets the default file pattern filter, and `ReportFileOwnerUser` sets the default list of users to include. + Files by property reports - `ReportPropertyName` sets the default classification property to analyze, and `ReportPropertyFilePattern` sets the default file pattern filter. + Files by file group reports - `ReportFileGroupIncluded` sets the default list of file groups to include. + Quota usage reports - `ReportQuotaMinimumUsage` sets the default minimum quota usage percentage. When you create a report, you can override any of these defaults by specifying the parameter explicitly in the report configuration. The global defaults only apply when you don't specify a value. ### Report limits Report limits Report limit settings control the maximum number of items to include in storage reports. These limits serve two purposes: 1. Performance management - Limiting the number of items in reports prevents reports from taking too long to generate or consuming excessive system resources. Large reports that analyze millions of files can take hours to complete and impact system performance. 1. Report usability - Reports with thousands of entries are difficult to review and analyze. Report limits ensure that reports remain focused on the most relevant data. You can set up granular control over report limits: + Overall limits - `ReportLimitMaxFile` limits the total number of files in any report, regardless of type. + Per-report-type limits - Settings like `ReportLimitMaxFileGroup`, ` ReportLimitMaxOwner`, and `ReportLimitMaxPropertyValue` limit the number of groups, owners, or property values to include in specific report types. + Per-group limits - Settings like `ReportLimitMaxFilesPerFileGroup`, ` ReportLimitMaxFilesPerOwner`, and ` ReportLimitMaxFilesPerPropertyValue` limit how many files to show within each group in the report. When a report reaches a limit, FSRM includes the items that consume the most storage space or are most relevant to the report type and indicates in the report that the limit was reached. ## FSRM settings commands FSRM settings commands You can access commands for retrieving and modifying global settings. Use these commands to configure system-wide FSRM behavior. ### List of FSRM Settings FSx remote PowerShell commands PowerShell commands **Note** All the examples in this page assume that you have defined the ` $FSxWindowsRemotePowerShellEndpoint` variable with your file system's Windows Remote PowerShell endpoint. You can find this endpoint in the Amazon FSx console on your file system's details page, or by using the AWS CLI `describe-file-systems` command. ### Get-FSxFSRMSetting Get-FSxFSRMSetting `Get-FSxFSRMSetting`: Retrieves the current File Server Resource Manager settings on your file system. Returns only the settings that can be modified using Set-FSxFSRMSetting. **Parameters:** None **Examples:** 1. Retrieve all current FSRM settings. ``` Invoke-Command -ComputerName $FSxWindowsRemotePowerShellEndpoint -ConfigurationName FSxRemoteAdmin -ScriptBlock { Get-FSxFSRMSetting } ``` ### Set-FSxFSRMSetting Set-FSxFSRMSetting `Set-FSxFSRMSetting`: Modifies global File Server Resource Manager settings on your file system. These settings provide default values for storage reports and control FSRM behavior. **Parameters:** **File screen audit settings:** + `ReportFileScreenAuditEnable (boolean)` - Optional. Controls whether file screening audit events are included in FSRM reports. + `ReportFileScreenAuditDaysSince (number)` - Optional. The default number of days to look back for file screening violations when generating FileScreenAuditFiles reports. + `ReportFileScreenAuditUser (array)` - Optional. An array of the default list of user accounts to include in FileScreenAuditFiles reports. **Default report filter settings:** + `ReportFileGroupIncluded (array)` - Optional. An array of file group names to include in reports by default. + `ReportFileOwnerFilePattern (string)` - Optional. The default file pattern for files by owner reports. Supports wildcards (`*` and `?`). + `ReportFileOwnerUser (array)` - Optional. An array of users in Domain\$1User format for files by owner reports. + `ReportLargeFileMinimum (number)` - Optional. The default minimum file size in bytes for large file reports. + `ReportLargeFilePattern (string)` - Optional. The default file pattern for large file reports. Supports wildcards (`*` and `?`). + `ReportLeastAccessedFilePattern (string)` - Optional. The default file pattern for least accessed file reports. Supports wildcards (`*` and `?`). + `ReportLeastAccessedMinimum (number)` - Optional. The default minimum number of days since last access for least accessed file reports. + `ReportMostAccessedFilePattern (string)` - Optional. The default file pattern for most accessed file reports. Supports wildcards (`*` and `?`). + `ReportMostAccessedMaximum (number)` - Optional. The default maximum number of days since last access for most accessed file reports. + `ReportPropertyFilePattern (string)` - Optional. The default file pattern for property reports. Supports wildcards (`*` and `?`). + `ReportPropertyName (string)` - Optional. The default property name for property reports. + `ReportQuotaMinimumUsage (number)` - Optional. The default minimum quota usage percentage for quota usage reports. **Report limit settings:** + `ReportLimitMaxDuplicateGroup (number)` - Optional. The maximum number of duplicate file groups to include in duplicate file reports. + `ReportLimitMaxFile (number)` - Optional. The maximum number of files to include in storage reports. + `ReportLimitMaxFileGroup (number)` - Optional. The maximum number of file groups to include in reports. + `ReportLimitMaxFileScreenEvent (number)` - Optional. The maximum number of file screen events to include in file screen audit reports. + `ReportLimitMaxFilesPerDuplicateGroup (number)` - Optional. The maximum number of files per duplicate group in duplicate file reports. + `ReportLimitMaxFilesPerFileGroup (number)` - Optional. The maximum number of files per file group in files by file group reports. + `ReportLimitMaxFilesPerOwner (number)` - Optional. The maximum number of files per owner in files by owner reports. + `ReportLimitMaxFilesPerPropertyValue (number)` - Optional. The maximum number of files per property value in files by property reports. + `ReportLimitMaxOwner (number)` - Optional. The maximum number of owners to include in files by owner reports. + `ReportLimitMaxPropertyValue (number)` - Optional. The maximum number of property values to include in files by property reports. + `ReportLimitMaxQuota (number)` - Optional. The maximum number of quotas to include in quota usage reports. **Other settings:** + `PassThru (boolean)` - Optional. If set to true, returns the modified settings object. **Examples:** 1. Configure default file screen auditing with a 30-day history. ``` Invoke-Command -ComputerName $FSxWindowsRemotePowerShellEndpoint -ConfigurationName FSxRemoteAdmin -ScriptBlock { Set-FSxFSRMSetting -ReportFileScreenAuditDaysSince 30 -PassThru } ``` 1. Configure default large file report settings. ``` Invoke-Command -ComputerName $FSxWindowsRemotePowerShellEndpoint -ConfigurationName FSxRemoteAdmin -ScriptBlock { Set-FSxFSRMSetting -ReportLargeFileMinimum 100MB -ReportLargeFilePattern "*.iso" -PassThru } ``` # Event Logs Event Logs When you enable FSRM on your file system, AWS FSx for Windows File Server generates event logs for file management activities and sends them to the destination you configured (AWS CloudWatch Logs or AWS Kinesis Data Firehose). These logs help you monitor FSRM operations, troubleshoot issues, and maintain audit trails of file management activities. ## What FSRM logs What FSRM logs When you enable FSRM on your file system, AWS FSx for Windows File Server logs events and sends them to your configured destination. The following events will be logged: + File screening violations - When users attempt to save files that are monitored by file screens that have event notification actions + Quota threshold notifications - When quota usage reaches configured thresholds that have event notification actions + FSRM service events – Confirmation of notification settings, service errors, and operational failures ## Accessing FSRM logs Accessing FSRM logs The location where you access FSRM logs depends on the destination you configured when enabling FSRM: CloudWatch Logs View logs in the CloudWatch Logs console by navigating to the log group you specified. You can search, filter, and analyze logs using CloudWatch Logs Insights, and set up CloudWatch alarms to notify you of specific events. Kinesis Data Firehose Logs are delivered to the destination configured in your Kinesis Data Firehose delivery stream, such as Amazon S3, AWS Redshift, or AWS OpenSearch Service. You can process and analyze logs using the tools and services integrated with your delivery stream. # Common Use Cases Common Use Cases This topic provides step-by-step examples for common File Server Resource Manager tasks. These examples demonstrate how to use and implement FSRM features to solve typical file management challenges. **Note** All the examples in this page assume that you have defined the ` $FSxWindowsRemotePowerShellEndpoint` variable with your file system's Windows Remote PowerShell endpoint. You can find this endpoint in the Amazon FSx console on your file system's details page, or by using the AWS CLI `describe-file-systems` command. ## Setting a hard quota on a folder Setting Hard Quotas This example shows how to create a hard quota that prevents users from storing more than 10 GB in a 'department' folder. **To set a quota on a folder:** 1. Create a hard quota with a 10 GB limit: ``` Invoke-Command -ComputerName $FSxWindowsRemotePowerShellEndpoint -ConfigurationName FSxRemoteAdmin -ScriptBlock { New-FSxFSRMQuota -Folder "share\department" -Size 10GB -Description "10 GB hard limit for department folder" } ``` 1. (Optional) Modify the quota to add a threshold notification at 85% usage: ``` $thresholds = [System.Collections.ArrayList]@() $threshold = @{ ThresholdPercentage = 85 Action = @( @{ ActionType = "Event" EventType = "Warning" MessageBody = "Department folder has reached 85% of quota limit" } ) } $null = $thresholds.Add($threshold) Invoke-Command -ComputerName $FSxWindowsRemotePowerShellEndpoint -ConfigurationName FSxRemoteAdmin -ArgumentList ($thresholds) -ScriptBlock { param($thresholds) Set-FSxFSRMQuota -Folder "share\department" -ThresholdConfigurations $Using:thresholds } ``` 1. Verify the quota was created: ``` Invoke-Command -ComputerName $FSxWindowsRemotePowerShellEndpoint -ConfigurationName FSxRemoteAdmin -ScriptBlock { Get-FSxFSRMQuota -Folder "share\department" } ``` ## Restricting specific file types using file groups Restricting File Types This example shows how to block users from saving audio and video files to a business documents folder using the default "`Audio and Video Files`" file group. **To restrict file types using file groups:** 1. Create an active file screen that blocks audio and video files: ``` Invoke-Command -ComputerName $FSxWindowsRemotePowerShellEndpoint -ConfigurationName FSxRemoteAdmin -ScriptBlock { New-FSxFSRMFileScreen -Folder "share\business-documents" -IncludeGroup "Audio and Video Files" -Description "Block media files in business documents folder" } ``` 1. (Optional) Update the file screen to add a notification when users attempt to save blocked files: ``` $notifications = [System.Collections.ArrayList]@() $eventNotification = @{ ActionType = "Event" EventType = "Warning" MessageBody = "User attempted to save blocked media file" } $null = $notifications.Add($eventNotification) Invoke-Command -ComputerName $FSxWindowsRemotePowerShellEndpoint -ConfigurationName FSxRemoteAdmin -ArgumentList $notifications -ScriptBlock { param($notifications) Set-FSxFSRMFileScreen -Folder "share\business-documents" -NotificationConfigurations $Using:notifications } ``` 1. Verify the file screen was created: ``` Invoke-Command -ComputerName $FSxWindowsRemotePowerShellEndpoint -ConfigurationName FSxRemoteAdmin -ScriptBlock { Get-FSxFSRMFileScreen -Folder "share\business-documents" } ``` ## Identify and classify PII data Classify PII Data This example shows how to automatically identify files containing Social Security numbers and classify them as containing personally identifiable information (PII). **To identify and classify PII data:** 1. Create a classification property for PII: ``` Invoke-Command -ComputerName $FSxWindowsRemotePowerShellEndpoint -ConfigurationName FSxRemoteAdmin -ScriptBlock { New-FSxFSRMClassificationPropertyDefinition -Name "ContainsPII" -Type OrderedList -PossibleValueConfigurations @( @{ Name = "Yes" }, @{ Name = "No" }) } ``` 1. Create a classification rule to detect Social Security numbers: **Note** The following Regular Expression will search files for text with the pattern XXX-XX-XXXX. For production use, consider using more sophisticated patterns or combining multiple detection methods. ``` Invoke-Command -ComputerName $FSxWindowsRemotePowerShellEndpoint -ConfigurationName FSxRemoteAdmin -ScriptBlock { New-FSxFSRMClassificationRule -Name "Detect_SSN" -Property "ContainsPII" -PropertyValue "Yes" -Namespace "share" -ClassificationMechanism "Content Classifier" -ContentRegularExpression "\b\d{3}-\d{2}-\d{4}\b" } ``` 1. Run classification: ``` Invoke-Command -ComputerName $FSxWindowsRemotePowerShellEndpoint -ConfigurationName FSxRemoteAdmin -ScriptBlock { Start-FSxFSRMClassification } ``` 1. (Optional) Configure continuous classification to automatically classify new files: ``` Invoke-Command -ComputerName $FSxWindowsRemotePowerShellEndpoint -ConfigurationName FSxRemoteAdmin -ScriptBlock { Set-FSxFSRMClassification -Continuous $true } ``` 1. Check for status (1 means completed): ``` Invoke-Command -ComputerName $FSxWindowsRemotePowerShellEndpoint -ConfigurationName FSxRemoteAdmin -ScriptBlock { Get-FSxFSRMClassification } ``` 1. After classification completes, you can view the classification properties assigned to files by right-clicking a file in Windows File Explorer, selecting **Properties**, and choosing the **Classification** tab. This tab displays all classification properties and their values for the file. ## Creating a retention policy for files Creating Retention Policies This example shows how to classify files by retention period based on their folder location, which you can then use with client-side PowerShell scripts to archive or delete files. **To create a retention policy for files:** 1. Create a classification property for retention period: ``` Invoke-Command -ComputerName $FSxWindowsRemotePowerShellEndpoint -ConfigurationName FSxRemoteAdmin -ScriptBlock { New-FSxFSRMClassificationPropertyDefinition -Name "RetentionPeriod" -Type String -Description "File retention period" } ``` 1. Create classification rules for different retention periods: + 7-year retention for legal documents under the folder **Legal Documents**: ``` Invoke-Command -ComputerName $FSxWindowsRemotePowerShellEndpoint -ConfigurationName FSxRemoteAdmin -ScriptBlock { New-FSxFSRMClassificationRule -Name "Legal_7Year" -Property "RetentionPeriod" -PropertyValue "7 years" -Namespace "share/Legal Documents" -ClassificationMechanism "Folder Classifier" } ``` + 3-year retention for financial records under the folder **Finance**: ``` Invoke-Command -ComputerName $FSxWindowsRemotePowerShellEndpoint -ConfigurationName FSxRemoteAdmin -ScriptBlock { New-FSxFSRMClassificationRule -Name "Finance_3Year" -Property "RetentionPeriod" -PropertyValue "3 years" -Namespace "share/Finance" -ClassificationMechanism "Folder Classifier" } ``` You can also classify by file content and search for strings like "Retention Period Seven Years". To achieve this, use the `ClassificationMechanism "Content Classifier"` and `ContentString "Retention seven years"`. 1. Run classification to apply retention properties: ``` Invoke-Command -ComputerName $FSxWindowsRemotePowerShellEndpoint -ConfigurationName FSxRemoteAdmin -ScriptBlock { Start-FSxFSRMClassification } ``` 1. (Optional) Configure continuous classification to automatically classify new files: ``` Invoke-Command -ComputerName $FSxWindowsRemotePowerShellEndpoint -ConfigurationName FSxRemoteAdmin -ScriptBlock { Set-FSxFSRMClassification -Continuous $true } ``` 1. Check for status (1 means completed): ``` Invoke-Command -ComputerName $FSxWindowsRemotePowerShellEndpoint -ConfigurationName FSxRemoteAdmin -ScriptBlock { Get-FSxFSRMClassification } ``` 1. After classification completes, you can view the classification properties assigned to files by right-clicking a file in Windows File Explorer, selecting **Properties**, and choosing the **Classification** tab. This tab displays all classification properties and their values for the file. 1. Once files are classified with retention periods, you can use client-side PowerShell scripts to archive or delete files based on their `RetentionPeriod` property and age. For example, you can scan the file system and compare file's age with their retention period classification. For more information, see [File Management Tasks](fsrm-file-management.md). ## Setting up common storage reports Setting Up Storage Reports This section shows how to create two commonly used storage reports: a large files report and a files by owner report. ### Large files report Large Files Report This example creates a monthly report that identifies files larger than 200 MB. **To create a large files report:** 1. Create a scheduled large files report: ``` $schedule = @{ Time = "2:00 AM" Monthly = @(1) # Run on the 1st of each month } Invoke-Command -ComputerName $FSxWindowsRemotePowerShellEndpoint -ConfigurationName FSxRemoteAdmin -ArgumentList $schedule -ScriptBlock { param($schedule) New-FSxFSRMStorageReport -Name "Monthly Large Files Report" -Namespace "share" -ReportType "LargeFiles" -LargeFileMinimum 200MB -ReportFormat "HTML","CSV" -ScheduleConfigurations $schedule } ``` 1. (Optional) Run the report immediately to test: ``` Invoke-Command -ComputerName $FSxWindowsRemotePowerShellEndpoint -ConfigurationName FSxRemoteAdmin -ScriptBlock { Start-FSxFSRMStorageReport -Name "Monthly Large Files Report" } ``` ### Files by owner report Files by Owner Report This example creates a weekly report that shows storage consumption by user. **To create a files by owner report:** 1. Create a scheduled files by owner report: ``` $schedule = @{ Time = "3:00 AM" Weekly = @('Sunday') } Invoke-Command -ComputerName $FSxWindowsRemotePowerShellEndpoint -ConfigurationName FSxRemoteAdmin -ArgumentList $schedule -ScriptBlock { param($schedule) New-FSxFSRMStorageReport -Name "Weekly Files by Owner Report" -Namespace "share" -ReportType "FilesByOwner" -ReportFormat "HTML","CSV" -ScheduleConfigurations $schedule } ``` 1. (Optional) Run the report immediately to test: ``` Invoke-Command -ComputerName $FSxWindowsRemotePowerShellEndpoint -ConfigurationName FSxRemoteAdmin -ScriptBlock { Start-FSxFSRMStorageReport -Name "Weekly Files by Owner Report" } ``` Access the generated reports by mapping the administrative D\$1 share. For more information, visit [Accessing storage reports](fsrm-storage-reports.md#fsrm-storage-reports-accessing).