# Administering FSx for Windows file systems Administering file systems Amazon FSx provides a wide range of administrative capabilities that help you easily manage and grow your Amazon FSx for Windows File Server file systems to meet changing workload and user requirements, and your organizations regulatory and compliance needs. The following is a list of some of the file system configurations that you can manage using the AWS Management Console, AWS CLI and API, the Amazon FSx CLI for remote management on PowerShell, and native Microsoft Windows Server graphical interfaces. + Storage capacity + Storage type + SSD IOPS + Throughput capacity + DNS aliases + Data deduplication + Shadow copies + Storage quotas + File access auditing + File shares The following sections provide information about the file system administrative features and setting that are available to you. We've included guidance to help you determine which options are best for your situation, and best practices where applicable. **Topics** + [ ## Amazon FSx file system status ](#file-system-lifecycle-states) + [ ## Using the Amazon FSx CLI for PowerShell ](#remote-pwrshell) + [ # Starting an Amazon FSx remote PowerShell session ](start-remote-powershell-session.md) + [ # One-time file system setup tasks using the Amazon FSx CLI for remote management on PowerShell ](one-time-admin-tasks.md) + [ # Troubleshooting access to the Amazon FSx CLI on PowerShell ](cant-access-rps.md) + [ ## File system maintenance window ](#maintenance-windows) + [ # Changing the weekly maintenance window ](update-maintenance-window.md) + [ # Managing DNS aliases ](managing-dns-aliases.md) + [ # User sessions and open files ](manage-sessions-and-files.md) + [ # File Server Resource Manager on FSx for Windows File Server ](managing-files-fsrm.md) + [ # Managing storage on FSx for Windows File Server ](managing-storage-configuration.md) + [ # Using DFS Namespaces ](using-dfs-namespaces.md) + [ # Managing throughput capacity ](managing-throughput-capacity.md) + [ # Managing network type ](manage-network-type.md) + [ # Tagging your Amazon FSx resources ](tag-resources.md) + [ # Update a file system using the AWS CLI ](walkthrough03-update-file-system.md) ## Amazon FSx file system status You can view the status of an Amazon FSx file system by using the Amazon FSx console, the AWS CLI command [describe-file-systems](https://docs.aws.amazon.com/cli/latest/reference/fsx/describe-file-systems.html), or the API operation [DescribeFileSystems](https://docs.aws.amazon.com/fsx/latest/APIReference/API_DescribeFileSystems.html). | File system status | Description | | --- | --- | | AVAILABLE | The file system is in a healthy state, and is reachable and available for use. | | CREATING | Amazon FSx is creating a new file system. | | DELETING | Amazon FSx is deleting an existing file system. | | UPDATING | The file system is undergoing a customer-initiated update. | | MISCONFIGURED | The file system is in an impaired state due to a change in your Active Directory environment. Your file system is either currently unavailable or at risk of losing availability, and backups may not succeed. For information on restoring availability, see [File system is in a misconfigured state](misconfigured-ad-config.md). | | MISCONFIGURED\$1UNAVAILABLE | The file system is currently unavailable due to a change in your Active Directory environment. For information on restoring availability, see [File system is in a misconfigured state](misconfigured-ad-config.md). | | FAILED | [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/fsx/latest/WindowsGuide/administering-file-systems.html) | ## Using the Amazon FSx CLI for PowerShell This chapter describes how to access the Amazon FSx CLI for remote management on PowerShell to perform file system administrative tasks for FSx for Windows file systems. You can also use the Microsoft Windows–native graphical user interface (GUI) to perform some administrative tasks. The Amazon FSx CLI for remote management on PowerShell enables file system administration for users in the file system administrators group. To start a remote PowerShell session on your FSx for Windows File Server file system, you first need to meet the following prerequisites: + Be able to connect to a Windows compute instance that has network connectivity with your FSx for Windows File Server file system. + Be logged into the Windows compute instance as a member of the file system administrators group. If you are using AWS Managed Microsoft AD, that is the *AWS Delegated FSx Administrators* group. If you are using a self-managed Microsoft Active Directory, that is the *Domain Admins* group or the custom group that you specified for administration when you created your file system. For more information, see [Best practices when using a self-managed Active Directory](self-managed-AD.md#self-managed-AD-best-practices). + Your file system's VPC security group inbound rules allow traffic on port 5985. The Amazon FSx CLI for remote management on PowerShell uses the following security features: + User credentials are authenticated using Kerberos authentication. + Management session communications between the connected client and file system are encrypted using Kerberos. You have two options to run remote management CLI commands on your Amazon FSx file system: + You can establish a long-running Remote PowerShell session and run the commands inside the session. + You can use the `Invoke-Command` to run a single command or a single block of commands without establishing a long-running Remote PowerShell session. If you want to set and pass variables as parameters to the remote management command, you will need to use `Invoke-Command`. **Note** For Multi-AZ file systems, you can only use the Amazon FSx CLI for Remote Management while the file system is using its preferred file server. For more information, see [Availability and durability: Single-AZ and Multi-AZ file systems](high-availability-multiAZ.md). You need to use the file system's *Windows Remote PowerShell Endpoint* to access the Remote PowerShell. The remote administration endpoint has the format of `amznfsxctlyaa1k.ActiveDirectory-DNS-name`, for example, `amznfsxctlyaa1k.corp.example.com`. You can find the endpoint name by using the AWS Management Console in the **File system details** page on the **Network & security** tab. Use the AWS CLI [https://docs.aws.amazon.com/v2/documentation/api/latest/reference/fsx/describe-file-systems.html](https://docs.aws.amazon.com/v2/documentation/api/latest/reference/fsx/describe-file-systems.html) command to view the `RemoteAdministrationEndpoint` property returned in the response. You can use the `Get-Command` cmdlet to retrieve information about the cmdlets, functions, and aliases available in PowerShell. For more information, see the Microsoft [Get-Command](https://learn.microsoft.com/en-us/powershell/module/microsoft.powershell.core/get-command?view=powershell-7.3) documentation. You can also run Amazon FSx CLI for remote management CLI on PowerShell commands on your file system using the `Invoke-Command` cmdlet, using the following syntax: ``` PS C:\Users\delegateadmin> Invoke-Command -ComputerName amznfsxctlyaa1k.corp.example.com -ConfigurationName FSxRemoteAdmin -scriptblock { fsx-command} ``` For instructions on how to start a long-lived Remote PowerShell session on your FSx for Windows File Server files system, see [Starting an Amazon FSx remote PowerShell session](start-remote-powershell-session.md) # Starting an Amazon FSx remote PowerShell session This topic provides instructions for starting a long-lived remote PowerShell session on your FSx for Windows File Server file server. **To start a remote PowerShell session on your file system** 1. Connect to a compute instance that has network connectivity with your file system as a user that is a member of the delegated FSx Administrators Group that you chose when you created the file system. 1. Open a Windows PowerShell window on the compute instance. 1. In the PowerShell, enter the following command to open a long-lived remote session on your Amazon FSx file system. Replace `Remote-PowerShell-Endpoint` with the Windows Remote PowerShell endpoint of file system that you want to administer. Use `FsxRemoteAdmin` as the session configuration name. ``` PS C:\Users\delegateadmin> enter-pssession -ComputerName Remote-PowerShell-Endpoint -ConfigurationName FsxRemoteAdmin [fs-0123456789abcdef0]: PS> ``` If your instance is not part of the Amazon FSx Active Directory domain, you are prompted to enter user credentials in a pop-up. Enter the credentials of the user that is a member of the FSx Administrators Group. If your instance is joined to the domain, you will not be asked for credentials. **Important** The Windows Remote PowerShell endpoint might change if you are using self-managed Active Directory configuration and change the service account without proper Active Directory Group Policy settings. For more information, see [Changing the Amazon FSx service account](changing-ad-service-account.md) for more details. # One-time file system setup tasks using the Amazon FSx CLI for remote management on PowerShell One-time file system setup tasks Use the following Amazon FSx CLI for Remote Management on PowerShell commands to quickly implement the file system administration tasks following our best practices. ## Managing storage consumption Use the following commands to manage your file system storage consumption. + To turn on data deduplication with the default schedule, run the following command. ``` Invoke-Command -ComputerName $FSxWindowsRemotePowerShellEndpoint -ConfigurationName FSxRemoteAdmin -ScriptBlock { Enable-FsxDedup } ``` Optionally, use the following command to get data deduplication operating on your files soon after a file is created, without requiring any minimum file age. ``` Invoke-Command -ComputerName $FSxWindowsRemotePowerShellEndpoint -ConfigurationName FSxRemoteAdmin -ScriptBlock { Set-FSxDedupConfiguration -MinimumFileAgeDays 0 } ``` For more information, see [Reducing storage costs with Data Deduplication](managing-storage-configuration.md#using-data-dedup).   + Use the following command to turn on user storage quotas in “Track” mode, which is for reporting purposes only and not for enforcement. ``` $QuotaLimit = Quota limit in bytes $QuotaWarningLimit = Quota warning threshold in bytes Invoke-Command -ComputerName $FSxWindowsRemotePowerShellEndpoint -ConfigurationName FSxRemoteAdmin -ScriptBlock { Enable-FSxUserQuotas -Track -DefaultLimit $Using:QuotaLimit -DefaultWarningLimit $Using:QuotaWarningLimit } ``` For more information, see [Managing storage quotas](managing-user-quotas.md). ## Turning on shadow copies to enable end-users to recover files and folders to previous versions Turn on shadow copies with the default schedule (weekdays 7 AM and 12 noon), as follows. ``` Invoke-Command -ComputerName $FSxWindowsRemotePowerShellEndpoint -ConfigurationName FSxRemoteAdmin -ScriptBlock { Set-FsxShadowStorage -Default } Invoke-Command -ComputerName $FSxWindowsRemotePowerShellEndpoint -ConfigurationName FSxRemoteAdmin -ScriptBlock { Set-FsxShadowCopySchedule -Default -Confirm:$False} ``` For more information, see [Configuring shadow copies to use the default storage and schedule](setting-up-fsx-shadow-copies.md). ## Enforcing encryption in transit The following command enforces encryption for clients connecting to your file system. ``` Invoke-Command -ComputerName $FSxWindowsRemotePowerShellEndpoint -ConfigurationName FSxRemoteAdmin -ScriptBlock { Set-FsxSmbServerConfiguration -EncryptData $True -RejectUnencryptedAccess $True -Confirm:$False} ``` You can close all open sessions and force clients currently connected to reconnect using encryption. ``` Invoke-Command -ComputerName $FSxWindowsRemotePowerShellEndpoint -ConfigurationName FSxRemoteAdmin -ScriptBlock { Close-FSxSmbSession -Confirm:$False} ``` For more information, see [Managing encryption in transit](encryption-in-transit.md#manage-encrypt-in-transit) and [User sessions and open files](manage-sessions-and-files.md). # Troubleshooting access to the Amazon FSx CLI on PowerShell There are a number of potential causes for being unable to connect to your file system using Remote PowerShell, each with their own resolution, as follows. To first ensure that you can connect successfully to the Windows Remote PowerShell Endpoint, you can also run a basic connectivity test. For example, you can run the `test-netconnection endpoint -port 5985` command. ## The file system's security group lacks the required inbound rules to allow a remote PowerShell connection The file system's security group must have an inbound rule that allows traffic on port 5985 in order to establish a Remote PowerShell session. For more information, see [Amazon VPC Security Groups](limit-access-security-groups.md#fsx-vpc-security-groups). ## You have an external trust configured between the AWS managed Microsoft Active Directory and your on-premises Active Directory In order to use the Amazon FSx Remote PowerShell with Kerberos authentication, you need to configure a local group policy on the client for forest search order. For more information, see the Microsoft documentation [Configure Kerberos Forest Search Order (KFSO)](https://docs.microsoft.com/en-us/previous-versions/windows/it-pro/windows-server-2008-R2-and-2008/hh921473(v=ws.10)?redirectedfrom=MSDN). ## A language localization error occurs when trying to initiate a remote PowerShell session You need to add the following `-SessionOption` to your command: `-SessionOption (New-PSSessionOption -uiCulture "en-US")` Following are two examples using `-SessionOption` when initiating a remote PowerShell session on your file system. ``` PS C:\Users\delegateadmin> Invoke-Command -ComputerName Windows Remote PowerShell Endpoint -ConfigurationName FSxRemoteAdmin -scriptblock {fsx-command} -SessionOption (New-PSSessionOption -uiCulture "en-US") ``` ``` PS C:\Users\delegateadmin> Enter-Pssession -ComputerName Windows Remote PowerShell Endpoint -ConfigurationName FsxRemoteAdmin -SessionOption (New-PSSessionOption -uiCulture "en-US") ``` ## File system maintenance window Maintenance window Amazon FSx for Windows File Server performs routine software patching for the Microsoft Windows Server software that it manages. The maintenance window specifies the day of the week and the time of day when this maintenance process begins. You can specify the start period of the maintenance window during file system creation. If you do not specify one, a 30-minute default maintenance start window is assigned. The duration of the maintenance window depends on multiple factors, including the scope of the maintenance, and the process of synchronizing any file read and write activity that occurs during maintenance between the primary and secondary servers for Multi-AZ file systems. For more information, see [Failing over process](high-availability-multiAZ.md#MultiAZ-Failover). FSx for Windows File Server lets you adjust the start time of your maintenance window to accommodate your workload and operational requirements. You can move the start time of your maintenance window as frequently as required, provided that a maintenance window start time is scheduled at least once every 14 days. If a patch is released and you haven’t scheduled a maintenance window within 14 days, FSx for Windows File Server proceeds with maintenance on the file system to ensure its security and reliability. For more information about how to adjust the start time of your file system's maintenance window, see [Changing the weekly maintenance window](update-maintenance-window.md). While patching is in progress, expect your Single-AZ file systems to be unavailable, typically for less than 20 minutes. Multi-AZ file systems remain available and automatically fail over and fail back between the preferred and the standby file servers. For more information, see [Failing over process](high-availability-multiAZ.md#MultiAZ-Failover). Because patching for Multi-AZ file systems involves failing over and failing back between the file servers, any file read and write activity occuring during this time must be synchronized between the preferred and the standby file servers. To reduce patching time, we recommend scheduling your maintenance window during idle periods when there's minimal load on your file system. **Note** To ensure data integrity during maintenance activity, Amazon FSx for Windows File Server completes any pending write operations to the underlying storage volumes hosting your file system before maintenance begins. # Changing the weekly maintenance window FSx for Windows File Server lets you adjust when your file system's maintenance window starts to accommodate your workload and operational requirements. You can use the AWS Management Console, AWS CLI, and Amazon FSx API to change when the weekly maintenance window starts, described in the following procedure. **To change the start time of the weekly maintenance window (console)** 1. Open the Amazon FSx console at [https://console.aws.amazon.com/fsx/](https://console.aws.amazon.com/fsx/). 1. Choose **File systems** in the left hand navigation column. 1. Choose the file system that you want to change the weekly maintenance window for. The file system details page displays. 1. Choose **Administration** to display the file system administration **Settings** panel. 1. Choose **Update** to display the **Change maintenance window** window. 1. Enter the new day and time that you want the weekly maintenance window to start. 1. Choose **Save** to save your changes. The new maintenance start time is displayed in the **Administration Settings** panel. To change the start time of the weekly maintenance window using the [update-file-system](https://docs.aws.amazon.com/cli/latest/reference/fsx/update-file-system.html) CLI command, see [Update a file system using the AWS CLI](walkthrough03-update-file-system.md). # Managing DNS aliases DNS aliases In addition to the default Domain Name System (DNS) name that Amazon FSx provides, you can also associate DNS aliases of your choosing with your file systems. With DNS aliases, you can continue using existing DNS names to access data stored on Amazon FSx when [migrating file system storage](migrate-to-fsx.md) from on-premises to Amazon FSx, without needing to update any tools or applications. You can associate DNS aliases with new and existing FSx for Windows File Server file systems, and when you restore a backup to a new file system, using the AWS Management Console and AWS CLI. You can associate up to 50 DNS aliases with a file system at any one time. **Note** Support for DNS aliases is available on FSx for Windows File Server file systems created after 12:00 pm ET on November 9, 2020. To use DNS aliases on a file system created before 12:00 pm ET on November 9, 2020, do the following: Take a backup of the existing file system. For more information, see [Working with user-initiated backups](using-backups.md#user-initiated-backups). Restore the backup to a new file system. For more information, see [Restoring backups to new file system](using-backups.md#restoring-backups). Once the new file system is available, you will be able to use DNS aliases to access it, using the information provided in this section. **Note** The information presented here assumes that you're working entirely within Active Directory and that you're not using external DNS providers. Third-party DNS providers may result in unexpected behavior. Amazon FSx only registers DNS records for a file system if the Active Directory domain that you are joining it to is using Microsoft DNS as the default DNS. If you are using a third-party DNS, you will need to manually set up DNS entries for your Amazon FSx file systems after you create your file system. For more information on choosing the correct IP addresses to use for the file system, see [Getting the correct file system IP addresses to use for manual DNS entries](file-system-ip-addresses-for-dns.md). You can associate DNS aliases with existing FSx for Windows File Server file systems, when you create new file systems, and when you create a new file system from a backup. You can associate up to 50 DNS aliases with a file system at any one time. In addition to associating DNS aliases with your file system, for clients to connect to the file system using the DNS aliases, you also must do the following: + Configure service principal names (SPNs) for Kerberos authentication and encryption. + Configure a DNS CNAME record for the DNS alias that resolves to the default DNS name for your Amazon FSx file system. For more information, see [Accessing data using DNS aliases](dns-aliases.md). A DNS alias name for your FSx for Windows File Server file system needs to meet the following requirements: + Must be formatted as a fully qualified domain name (FQDN). + Can contain alphanumeric characters and hyphens (‐). + Cannot start or end with a hyphen. + Can start with a numeric. For DNS alias names, Amazon FSx stores alphabetic characters as lowercase letters (a-z), regardless of how you specify them: as uppercase letters, lowercase letters, or the corresponding letters in escape codes. If you try to associate an alias that is already associated with the file system, it has no effect. If you try to disassociate an alias from a file system that is not associated with the file system, Amazon FSx responds with a bad request error. **Note** When Amazon FSx adds or removes aliases on a file system, connected clients are temporarily disconnected and will automatically reconnect to the file system. Any files that were open by clients mapping a non-Continuously-Available (non-CA) share at the time of disconnection must be reopened by the client. **Topics** + [ ## DNS alias status ](#alias-status) + [ ## Using DNS aliases with Kerberos authentication ](#aliases-and-kerberos) + [ # Viewing DNS aliases for file systems and backups ](view-aliases.md) + [ # Associating DNS aliases with file systems ](add-alias-new-filesystem.md) + [ # Managing DNS aliases on existing file systems ](manage-aliases-existing-fs.md) ## DNS alias status DNS aliases can have one of the following status values: + Available – The DNS alias is associated with an Amazon FSx file system. + Creating – Amazon FSx is creating the DNS alias and associating it with the file system. + Deleting – Amazon FSx is disassociating the DNS alias from the file system and deleting it. + Failed to create – Amazon FSx was unable to associate the DNS alias with the file system. + Failed to delete – Amazon FSx was unable to disassociate the DNS alias from the file system. ## Using DNS aliases with Kerberos authentication Using DNS aliases with Kerberos We recommend that you use Kerberos-based authentication and encryption in transit with Amazon FSx. Kerberos provides the most secure authentication for clients accessing your file system. To enable Kerberos authentication for clients that access your Amazon FSx file system using a DNS alias, you must configure service principal names (SPNs) that correspond to the DNS alias on your file system’s Active Directory computer object. If you have SPNs configured for the DNS alias that you've assigned to another file system on a computer object in your Active Directory, you must first remove those SPNs before adding SPNs to your file system’s computer object. For more information, see [Configure service principal names (SPNs) for Kerberos](step2-configure-spn-kerberos.md). # Viewing DNS aliases for file systems and backups Viewing existing DNS aliases You can view the DNS aliases currently associated with your FSx for Windows File Server file systems and backups using the AWS Management Console, the AWS CLI, and API, as described in the following procedures. **To view DNS aliases associated with file systems** + Using the console — Choose a file system to view the **File systems** detail page. Choose the **Network & security** tab to view the **DNS aliases**. + Using the CLI or API — Use the `describe-file-system-aliases` CLI command or the [DescribeFileSystemAliases](https://docs.aws.amazon.com/fsx/latest/APIReference/API_DescribeFileSystemAliases.html) API operation. **To view DNS aliases associated with backups** + Using the console — In the navigation pane, choose **Backups**, and then choose the backup that you want to view. In the **Summary** pane, view the **DNS aliases** field. + Using the CLI or API — Use the `describe-backups` CLI command or the [DescribeBackups](https://docs.aws.amazon.com/fsx/latest/APIReference/API_DescribeBackups.html) API operation. # Associating DNS aliases with file systems You can associate DNS aliases when creating a new FSx for Windows File Server file system from scratch, or when restoring a backup to a new file system, using the AWS Management Console, AWS CLI, and API, described the following procedures. ## To associate DNS aliases when creating a new file system (console) 1. Open the Amazon FSx console at [https://console.aws.amazon.com/fsx/](https://console.aws.amazon.com/fsx/). 1. Follow the procedure for creating a new file system described in [Step 5. Create your file system](getting-started.md#getting-started-step1) in the Getting Started section. 1. In the **Access - optional** section of the **Create file system** wizard, enter the DNS aliases that you want to associate with your file system. ![\[\]](http://docs.aws.amazon.com/fsx/latest/WindowsGuide/images/FSxW-create-fs-Access-aliases.png) 1. When the file system is **Available**, you can access it using the DNS alias by configuring service principal names (SPNs) and updating or creating a DNS CNAME record for the alias. For more information, see [Accessing data using DNS aliases](dns-aliases.md). ## To associate DNS aliases when creating a new Amazon FSx file system (CLI) 1. When creating a new file system, use the [Alias](https://docs.aws.amazon.com/fsx/latest/APIReference/API_Alias.html) property with the [CreateFileSystem](https://docs.aws.amazon.com/fsx/latest/APIReference/API_CreateFileSystem.html) API operation to associate DNS aliases with the new file system. ``` aws fsx create-file-system \ --file-system-type WINDOWS \ --storage-capacity 2000 \ --storage-type SSD \ --subnet-ids subnet-123456 \ --windows-configuration Aliases=[financials.corp.example.com,accts-rcv.corp.example.com] ``` 1. When the file system is **Available**, you can access it using the DNS alias by configuring service principal names (SPNs) and updating or creating a DNS CNAME record for the alias. For more information, see [Accessing data using DNS aliases](dns-aliases.md). ## To add or remove DNS aliases when restoring a backup (CLI) 1. When creating a new file system from a backup of an existing file system, you can use the [Aliases](https://docs.aws.amazon.com/fsx/latest/APIReference/API_Aliases.html) property with the [CreateFileSystemFromBackup](https://docs.aws.amazon.com/fsx/latest/APIReference/API_CreateFileSystemFromBackup.html) API operation as follows: + Any aliases associated with the backup are associated with the new file system by default. + To create a file system without preserving any aliases from the backup, use the `Aliases` property with an empty set. To associate additional DNS aliases, use the `Aliases` property and include both the original aliases associated with the backup and the new aliases you want to associate. The following CLI command associates two aliases with the file system Amazon FSx is creating from a backup. ``` aws fsx create-file-system-from-backup \ --backup-id backup-0123456789abcdef0 --storage-capacity 2000 \ --storage-type HDD \ --subnet-ids subnet-123456 \ --windows-configuration Aliases=[transactions.corp.example.com,accts-rcv.corp.example.com] ``` 1. When the file system is **Available**, you can access it using the DNS alias by configuring service principal names (SPNs) and updating or creating a DNS CNAME record for the alias. For more information, see [Accessing data using DNS aliases](dns-aliases.md). # Managing DNS aliases on existing file systems You can add and remove aliases on existing FSx for Windows File Server file systems using the AWS Management Console and AWS CLI, as described in the following procedures. ## To manage file system DNS aliases (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 manage DNS aliases for. 1. On the **Network & security** tab, choose **Manage** for **DNS aliases** to display the **Manage DNS aliases** window. + To associate DNS aliases – In the **Associate new aliases** box, enter the DNS aliases that you want to associate. Choose **Associate**. + To disassociate DNS aliases – In the **Current aliases** list, choose the aliases to disassociate from. Choose **Disassociate**. You can monitor the status of the aliases you have managed in the **Current aliases** list. Refresh the list to update the status. It takes up to 2.5 minutes for an alias to be associated or disassociated with a file system. 1. When the alias is **Available**, you can access your file system using the DNS alias by configuring service principal names (SPNs) and updating or creating a DNS CNAME record for the alias. For more information, see [Accessing data using DNS aliases](dns-aliases.md). ## To associate DNS aliases with existing file systems (CLI) 1. Use the `associate-file-system-aliases` CLI command or the [AssociateFileSystemAliases](https://docs.aws.amazon.com/fsx/latest/APIReference/API_AssociateFileSystemAliases.html) API operation to associate DNS aliases with an existing file system. The following CLI request associates two aliases with the specified file system. ``` aws fsx associate-file-system-aliases \ --file-system-id fs-0123456789abcdef0 \ --aliases financials.corp.example.com transfers.corp.example.com ``` The response shows the status of the aliases that Amazon FSx is associating with the file system. ``` { "Aliases": [ { "Name": "financials.corp.example.com", "Lifecycle": CREATING }, { "Name": "transfers.corp.example.com", "Lifecycle": CREATING } ] } ``` 1. Use the `describe-file-system-aliases` CLI command ([DescribeFileSystemAliases](https://docs.aws.amazon.com/fsx/latest/APIReference/API_DescribeFileSystemAliases.html) is the equivalent API operation) to monitor the status of the aliases that you are associating. 1. When the `Lifecycle` has a value of AVAILABLE (a process that can take up to 2.5 minutes), you can access your file system using the DNS alias by configuring service principal names (SPNs) and updating or creating a DNS CNAME record for the alias. For more information, see [Accessing data using DNS aliases](dns-aliases.md). ## To disassociate DNS aliases from file systems (CLI) + Use the `disassociate-file-system-aliases` CLI command or the [DisassociateFileSystemAliases](https://docs.aws.amazon.com/fsx/latest/APIReference/API_DisassociateFileSystemAliases.html) API operation to disassociate DNS aliases from an existing file system. The following command disassociates one alias from a file system. ``` aws fsx disassociate-file-system-aliases \ --file-system-id fs-0123456789abcdef0 \ --aliases financials.corp.example.com ``` The response shows the status of the aliases that Amazon FSx is disassociating from the file system. ``` { "Aliases": [ { "Name": "financials.corp.example.com", "Lifecycle": DELETING } ] } ``` Use the `describe-file-system-aliases` CLI command ([DescribeFileSystemAliases](https://docs.aws.amazon.com/fsx/latest/APIReference/API_DescribeFileSystemAliases.html) is the equivalent API operation) to monitor the status of the aliases. It takes up to 2.5 minutes for the alias to be deleted. # User sessions and open files You can monitor connected user sessions and open files on your FSx for Windows File Server file system using the Shared Folders tool. The Shared Folders tool provides a central location to monitor who is connected to the file system, along with what files are open and by whom. You can use this tool to do the following: + Restore access to locked files. + Disconnect a user session, which closes all files opened by that user. You can use the Windows-native Shared Folders GUI tool and the Amazon FSx CLI for remote management on PowerShell to manage user sessions and open files on your FSx for Windows File Server file system. ## Using the GUI to manage users and sessions The following procedures detail how you can manage user sessions and open files on your Amazon FSx file system using the Microsoft Windows shared folders tool. ### To launch the shared folders tool 1. Launch your Amazon EC2 instance and connect it to the Microsoft Active Directory that your Amazon FSx file system is joined to. To do this, choose one of the following procedures from the *AWS Directory Service Administration Guide*: + [Seamlessly join a Windows EC2 instance](https://docs.aws.amazon.com/directoryservice/latest/admin-guide/launching_instance.html) + [Manually join a Windows instance](https://docs.aws.amazon.com/directoryservice/latest/admin-guide/join_windows_instance.html) 1. Connect to your instance as a user that is a member of the file system administrators group. In AWS Managed Microsoft Active Directory, this group is called AWS Delegated FSx Administrators. In your self-managed Microsoft Active Directory, this group is called Domain Admins or the custom name for the administrators group that you provided during creation. For more information, see [Connecting to Your Windows Instance](https://docs.aws.amazon.com/AWSEC2/latest/WindowsGuide/connecting_to_windows_instance.html) in the *Amazon EC2 User Guide*. 1. Open the **Start** menu and run **fsmgmt.msc** using `Run As Administrator`. Doing this opens the Shared Folders GUI tool. 1. For **Action**, choose **Connect to another computer**. 1. For **Another computer**, enter the DNS name of your Amazon FSx file system, for example `fs-012345678901234567.ad-domain.com`. 1. Choose **OK**. An entry for your Amazon FSx file system then appears in the list for the Shared Folders tool. ### To manage user sessions (GUI) In the Shared Folders tool, choose **Sessions** to view all the user sessions that are connected to your FSx for Windows File Server file system. If a user or application is accessing a file share on your Amazon FSx file system, this snap-in shows you their session. You can disconnect sessions by opening the context (right-click) menu for a session and choosing **Close Session**. ![\[The Shared Folders tool displaying the user sessions that are connected to your FSx for Windows File Server file system.\]](http://docs.aws.amazon.com/fsx/latest/WindowsGuide/images/usersessions-close.png) To disconnect all open sessions, open the context (right-click) menu for **Sessions**, choose **Disconnect All Sessions**, and confirm your action. ![\[The Shared Folders tool with the context-menu for Sessions open.\]](http://docs.aws.amazon.com/fsx/latest/WindowsGuide/images/discnnct-all-sessions.png) ### To manage open files (GUI) In the Shared Folders tool, choose **Open Files** to view all the files on the system that are currently open. The view also shows which users have the files or folders open. This information can be helpful in tracking down why other users cannot open certain files. You can close any file that any user has open simply by opening the context (right-click) menu for the file's entry in the list and choosing **Close Open File**. ![\[The Open files tab in the Shared Folders tool.\]](http://docs.aws.amazon.com/fsx/latest/WindowsGuide/images/clse-opn-file.png) To disconnect all open files on the file system, the context (right-click) menu for **Open Files** and choose **Disconnect All Open Files**, and confirm your action. ![\[The context-menu for Open files in the Shared Folders tool.\]](http://docs.aws.amazon.com/fsx/latest/WindowsGuide/images/clse-ALL-opn-file.png) ## Using PowerShell to manage user sessions and open files You can manage active user sessions and open files on your file system using the Amazon FSx CLI for remote management on PowerShell. To learn how to use this CLI, see [Using the Amazon FSx CLI for PowerShell](administering-file-systems.md#remote-pwrshell). Following are commands that you can use for user session and open file management. | Command | Description | | --- | --- | | **Get-FSxSmbSession** | Retrieves information about the Server Message Block (SMB) sessions that are currently established between the file system and the associated clients. | | **Close-FSxSmbSession** | Ends an SMB session. | | **Get-FSxSmbOpenFile** | Retrieves information about files that are open for the clients connected to the file system. | | **Close-FSxSmbOpenFile** | Closes a file that is open for one of the clients of the SMB server. | The online help for each command provides a reference of all command options. To access this help, run the command with a **-?**, for example **Get-FSxSmbSession -?**. # 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). # Managing storage on FSx for Windows File Server Managing storage Your file system's storage configuration includes the amount of provisioned storage capacity, the storage type, and if the storage type is solid state drive (SSD), the amount of SSD IOPS. You can configure these resources, along with the file system's throughput capacity, when creating a file system and after it's created, to achieve the desired performance for your workload. Learn how to manage your file system's storage and storage-related performance using the AWS Management Console, AWS CLI, and the Amazon FSx CLI for remote management on PowerShell by exploring the following topics. **Topics** + [ ## Optimizing storage costs ](#optimize-storage-costs) + [ ## Managing storage capacity ](#managing-storage-capacity) + [ ## Managing your file system's storage type ](#managing-storage-type) + [ ## Managing SSD IOPS ](#managing-provisioned-ssd-iops) + [ ## Reducing storage costs with Data Deduplication ](#using-data-dedup) + [ # Managing storage quotas ](managing-user-quotas.md) + [ # Increasing file system storage capacity ](increase-storage-capacity.md) + [ # Monitoring storage capacity increases ](monitoring-storage-capacity-increase.md) + [ # Increasing the storage capacity of an FSx for Windows File Server file system dynamically ](automate-storage-capacity-increase.md) + [ # Updating the storage type of a FSx for Windows file system ](updating-storage-type.md) + [ # Monitoring storage type updates ](monitoring-storage-type-updates.md) + [ # Updating a file system's SSD IOPS ](how-to-provision-ssd-iops.md) + [ # Monitoring provisioned SSD IOPS updates ](monitoring-provisioned-ssd-iops.md) + [ # Managing data deduplication ](managing-data-dedup.md) + [ # Troubleshooting data deduplication ](data-dedup-ts.md) ## Optimizing storage costs You can optimize your storage costs using the storage configuration options available in FSx for Windows. **Storage type options**—FSx for Windows File Server provides two storage types, hard disk drives (HDD) and solid state drives (SSD)—to enable you to optimize cost/performance to meet your workload needs. HDD storage is designed for a broad spectrum of workloads, including home directories, user and departmental shares, and content management systems. SSD storage is designed for the highest-performance and most latency-sensitive workloads, including databases, media processing workloads, and data analytics applications. For more information about storage types and file system performance, see [FSx for Windows File Server performancePerformance](performance.md). **Data deduplication**—Large datasets often have redundant data, which increases data storage costs. For example, user file shares can have multiple copies of the same file, stored by multiple users. Software development shares can contain many binaries that remain unchanged from build to build. You can reduce your data storage costs by turning on *data deduplication* for your file system. When it's turned on, data deduplication automatically reduces or eliminates redundant data by storing duplicated portions of the dataset only once. For more information about data deduplication, and how to easily turn it on for your Amazon FSx file system, see [Reducing storage costs with Data Deduplication](#using-data-dedup). ## Managing storage capacity You can increase your FSx for Windows file system's storage capacity as your storage requirements change. You can do so using the Amazon FSx console, the Amazon FSx API, or the AWS Command Line Interface (AWS CLI). Factors to consider when planning a storage capacity increase include knowing when you need to increase storage capacity, understanding how Amazon FSx processes storage capacity increases, and tracking the progress of a storage increase request. You can only increase a file system's storage capacity; you cannot decrease storage capacity. **Note** You can't increase storage capacity for file systems created before June 23, 2019 or file systems restored from a backup belonging to a file system that was created before June 23, 2019. When you increase the storage capacity of your Amazon FSx file system, Amazon FSx adds a new, larger set of disks to your file system behind the scenes. Amazon FSx then runs a storage optimization process in the background to transparently migrate data from the old disks to the new disks. Storage optimization can take between a few hours and several days, depending on the storage type and other factors, with minimal noticeable impact on the workload performance. During this optimization, backup usage is temporarily higher, because both the old and new storage volumes are included in the file system-level backups. Both sets of storage volumes are included to ensure that Amazon FSx can successfully take and restore from backups even during storage scaling activity. The backup usage reverts to its previous baseline level after the old storage volumes are no longer included in the backup history. When the new storage capacity becomes available, you are billed only for the new storage capacity. The following illustration shows the four main steps of the process that Amazon FSx uses when increasing a file system's storage capacity. ![\[Diagram showing the 4 steps of the storage scaling process.\]](http://docs.aws.amazon.com/fsx/latest/WindowsGuide/images/storage-scaling-flow.png) You can track the progress of storage optimization, SSD storage capacity increases, or SSD IOPS updates at any time using the Amazon FSx console, CLI, or API. For more information, see [Monitoring storage capacity increases](monitoring-storage-capacity-increase.md). ### What to know about increasing a file system's storage capacity What to know about increasing storage Here are a few important items to consider when increasing storage capacity: + **Increase only** – You can only *increase* the amount of storage capacity for a file system; you can't decrease storage capacity. + **Minimum increase** – Each storage capacity increase must be a minimum of 10 percent of the file system's current storage capacity, up to the maximum allowed value of 65,536 GiB. + **Minimum throughput capacity** – To increase storage capacity, a file system must have a minimum throughput capacity of 16 MBps. This is because the storage optimization step is a throughput-intensive process. + **Time between increases** – You can't make further storage capacity increases on a file system until 6 hours after the last increase was requested, or until the storage optimization process has completed, whichever time is longer. Storage optimization can take from a few hours up to a few days to complete. To minimize the time it takes for storage optimization to complete, we recommend increasing your file system's throughput capacity before increasing storage capacity (the throughput capacity can be scaled back down after storage scaling completes), and increasing storage capacity when there is minimal traffic on the file system. **Note** Certain file system events can consume disk I/O performance resources For example: The optimization phase of storage capacity scaling can generate increased disk throughput, and potentially cause performance warnings. For more information, see [Performance warnings and recommendations](monitoring-cloudwatch.md#performance-insights-FSxW). ### Knowing when to increase storage capacity Increase your file system's storage capacity when it's running low on free storage capacity. Use the `FreeStorageCapacity` CloudWatch metric to monitor the amount of free storage available on the file system. You can create an Amazon CloudWatch alarm on this metric and get notified when it drops below a specific threshold. For more information, see [Monitoring with Amazon CloudWatch](monitoring-cloudwatch.md). We recommend maintaining at least 20% of free storage capacity at all times on your file system. Using all of your storage capacity can negatively impact your performance and might introduce data inconsistencies. You can automatically increase your file system's storage capacity when the amount of free storage capacity falls below a defined threshold that you specify. Use the AWS‐developed custom CloudFormation template to deploy all of the components required to implement the automated solution. For more information, see [Increasing storage capacity dynamically](automate-storage-capacity-increase.md). ### Storage capacity increases and file system performance Performance impact during a storage capacity increase Most workloads experience minimal performance impact while Amazon FSx runs the storage optimization process in the background after the new storage capacity is available. However, file systems with HDD storage type and workloads involving large numbers of end users, high levels of I/O, or datasets that have large numbers of small files could temporarily experience reduction in the performance. For these cases, we recommend that you first increase your file system's throughput capacity before increasing storage capacity. For these types of workloads, we also recommend changing throughput capacity during idle periods when there is minimal load on your file system. This enables you to continue providing the same level of throughput to meet your application’s performance needs. For more information, see [Managing throughput capacity](managing-throughput-capacity.md). ## Managing your file system's storage type Managing storage types You can change your file system storage type from HDD to SSD using the AWS Management Console and AWS CLI. When you change the storage type to SSD, keep in mind that you can't update your file system configuration again until 6 hours after the last update was requested, or until the storage optimization process is complete—whichever time is longer. Storage optimization can take between a few hours and a few days to complete. To minimize this time, we recommend updating your storage type when there is minimal traffic on your file system. For more information, see [Updating the storage type of a FSx for Windows file system](updating-storage-type.md). You can't change your file system storage type from SSD to HDD. If you want to change a file system's storage type from SSD to HDD, you will need to restore a backup of the file system to a new file system that you configure to use HDD storage. For more information, see [Restoring backups to new file system](using-backups.md#restoring-backups). ### About storage types You can configure your FSx for Windows File Server file system to use either the solid state drive (SSD) or the magnetic hard disk drive (HDD) storage type. **SSD storage** is appropriate for most production workloads that have high performance requirements and latency-sensitivity. Examples of these workloads include databases, data analytics, media processing, and business applications. We also recommend SSD for use cases involving large numbers of end users, high levels of I/O, or datasets that have large numbers of small files. Lastly, we recommend using SSD storage if you plan to enable shadow copies. You can configure and scale SSD IOPS for file systems with SSD storage, but not HDD storage. **HDD storage** is designed for a broad range of workloads—including home directories, user and departmental file shares, and content management systems. HDD storage comes at a lower cost relative to SSD storage, but with higher latencies and lower levels of disk throughput and disk IOPS per unit of storage. It might be suitable for general-purpose user shares and home directories with low I/O requirements, large content management systems (CMS) where data is retrieved infrequently, or datasets with small numbers of large files. For more information, see [Storage configuration & performance](performance.md#storage-capacity-and-performance). ## Managing SSD IOPS For file systems configured with SSD storage, the amount of SSD IOPS determines the amount of disk I/O available when your file system has to read data from and write data to disk, as opposed to data that is in cache. You can select and scale the amount of SSD IOPS independently of storage capacity. The maximum SSD IOPS that you can provision is dependent on the amount of storage capacity and throughput capacity you select for your file system. If you attempt to increase your SSD IOPS above the limit that's supported by your throughput capacity, you might need to increase your throughput capacity to get that level of SSD IOPS. For more information, see [FSx for Windows File Server performancePerformance](performance.md) and [Managing throughput capacity](managing-throughput-capacity.md). Here are a few important items to know about updating a file system's provisioned SSD IOPS: + Choosing an IOPS mode – there are two IOPS modes to choose from: + **Automatic** – choose this mode and Amazon FSx will automatically scale your SSD IOPS to maintain 3 SSD IOPS per GiB of storage capacity, up to 400,000 SSD IOPS per file system. + **User-provisioned** – choose this mode so that you can specify the number of SSD IOPS within the range of 96–400,000. Specify a number between 3–50 IOPS per GiB of storage capacity for all AWS Regions where Amazon FSx is available, or between 3–500 IOPS per GiB of storage capacity in US East (N. Virginia), US West (Oregon), US East (Ohio), Europe (Ireland), Asia Pacific (Tokyo), and Asia Pacific (Singapore). When you choose the user-provisiohed mode, and the amount of SSD IOPS you specify is not at least 3 IOPS per GiB, the request fails. For higher levels of provisioned SSD IOPS, you pay for the average IOPS above 3 IOPS per GiB per file system. + **Storage capacity updates** – If you increase your file system's storage capacity, and the amount requires by default an amount of SSD IOPS that is greater than your current user-provisioned SSD IOPS level, Amazon FSx automatically switches your file system to Automatic mode and your file system will have a minimum of 3 SSD IOPS per GiB of storage capacity. + **Throughput capacity updates** – If you increase your throughput capacity, and the maximum SSD IOPS supported by your new throughput capacity is higher than your user-provisioned SSD IOPS level, Amazon FSx automatically switches your file system to Automatic mode. + **Frequency of SSD IOPS increases** – You can't make further SSD IOPS increases, throughput capacity increases, or storage type updates on a file system until 6 hours after the last increase was requested, or until the storage optimization process has completed—whichever time is longer. Storage optimization can take from a few hours up to a few days to complete. To minimize the time it takes for storage optimization to complete, we recommend scaling SSD IOPS when there is minimal traffic on the file system. **Note** Note that throughput capacity levels of 4,608 MBps and higher are supported only in the following AWS Regions: US East (N. Virginia), US West (Oregon), US East (Ohio), Europe (Ireland), Asia Pacific (Tokyo), and Asia Pacific (Singapore). For more information about how update the amount of provisioned SSD IOPS for your FSx for Windows File Server file system, see [Updating a file system's SSD IOPS](how-to-provision-ssd-iops.md). ## Reducing storage costs with Data Deduplication Data deduplication Data Deduplication, often referred to as Dedup for short, helps storage administrators reduce costs that are associated with duplicated data. With FSx for Windows File Server, you can use Microsoft Data Deduplication to identify and eliminate redundant data. Large datasets often have redundant data, which increases the data storage costs. For example: + User file shares may have many copies of the same or similar files. + Software development shares can have many binaries that remain unchanged from build to build. You can reduce your data storage costs by enabling data deduplication for your file system. *Data deduplication *reduces or eliminates redundant data by storing duplicated portions of the dataset only once. When you enable Data Deduplication, Data compression is enabled by default, compressing the data after deduplication for additional savings. Data Deduplication optimizes redundancies without compromising data fidelity or integrity. Data deduplication runs as a background process that continually and automatically scans and optimizes your file system, and it is transparent to your users and connected clients. The storage savings that you can achieve with data deduplication depends on the nature of your dataset, including how much duplication exists across files. Typical savings average 50–60 percent for general-purpose file shares. Within shares, savings range from 30–50 percent for user documents to 70–80 percent for software development datasets. You can measure potential deduplication savings using the `Measure-FSxDedupFileMetadata` remote PowerShell command described below. You can also customize data deduplication to meet your specific storage needs. For example, you can configure deduplication to run only on certain file types, or you can create a custom job schedule. Because deduplication jobs can consume file server resources, we recommend monitoring the status of your deduplication jobs using the `Get-FSxDedupStatus`. For information about configuring data deduplication on your file system, see [Managing data deduplication](managing-data-dedup.md). For information on resolving issues related to data deduplication, see [ Troubleshooting data deduplication Learn to identify and resolve issues that arise when using data deduplication on your FSx for Windows File Server file systems. data deduplicationinsufficient memorypowershell Use the following information to help troubleshoot some common issues when configuring and using data deduplication. Data deduplication is not working To see the current status of data deduplication, run the `Get-FSxDedupStatus` PowerShell command to view the completion status for the most recent deduplication jobs. If one or more jobs is failing, you may not see an increase in free storage capacity on your file system. The most common reason for deduplication jobs failing is insufficient memory. Microsoft [recommends](https://docs.microsoft.com/en-us/windows-server/storage/data-deduplication/install-enable#faq) optimally having 1 GB of memory per 1 TB of logical data (or at a minimum 350 MB per 1 TB of logical data). Use the [Amazon FSx performance table](performance.md#performance-table) to determine the memory associated with your file system's throughput capacity and ensure the memory resources are sufficient for the size of your data. If it is not, you need to [increase the file system's throughput capacity](managing-throughput-capacity.md) to the level that meets the memory requirements of 1 GB per 1 TB of logical data. Deduplication jobs are configured with the Windows recommended default of 25% memory allocation, which means that for a file system with 32 GB of memory, 8 GB will be available for deduplication. The memory allocation is configurable (using the `Set-FSxDedupSchedule` command with parameter `–Memory`). Be aware that using a higher memory allocation for dedup may impact file system performance. You can modify the configuration of deduplication jobs to reduce the amount of memory required. For example, you can constrain the optimization to run on specific file types or folders, or set a minimum file size and age for optimization. We also recommend configuring deduplication jobs to run during idle periods when there is minimal load on your file system. You may also see errors if deduplication jobs have insufficient time to complete. You may need to change the maximum duration of jobs, as described in [Modifying a data deduplication schedule](managing-data-dedup.md#set-dedup-sched). If deduplication jobs have been failing for a long period of time, and there have been changes to the data on the file system during this period, subsequent deduplication jobs may require more resources to complete successfully for the first time. Deduplication values are unexpectedly set to 0 The values for `SavedSpace` and `OptimizedFilesSavingsRate` are unexpectedly 0 for a file system on which you have configured data deduplication. This can occur during the storage optimization process when you increase the file system's storage capacity. When you increase a file system's storage capacity, Amazon FSx cancels existing data deduplication jobs during the storage optimization process, which migrates data from the old disks to the new, larger disks. Amazon FSx resumes data deduplication on the file system once the storage optimization job completes. For more information about increasing storage capacity and storage optimization, see [Managing storage capacity](managing-storage-configuration.md#managing-storage-capacity). Space is not freed up on file system after deleting files The expected behavior of data deduplication is that if the data that was deleted was something that dedup had saved space on, then the space is not actually freed up on your file system until the garbage collection job runs. A practice you may find helpful is to set the schedule to run the garbage collection job right after you delete a large number of files. After the garbage collection job finishes, you can set the garbage collection schedule back to its original settings. This ensures you can quickly see the space from your deletions immediately. Use the following procedure to set the garbage collection job to run in 5 minutes. To verify that data deduplication is enabled, use the `Get-FSxDedupStatus` command. For more information on the command and its expected output, see [Viewing the amount of saved space](managing-data-dedup.md#get-dedup-status). Use the following to set the schedule to run the garbage collection job 5 minutes from now. ``` $FiveMinutesFromNowUTC = ((get-date).AddMinutes(5)).ToUniversalTime() $DayOfWeek = $FiveMinutesFromNowUTC.DayOfWeek $Time = $FiveMinutesFromNowUTC.ToString("HH:mm") Invoke-Command -ComputerName ${RPS_ENDPOINT} -ConfigurationName FSxRemoteAdmin -ScriptBlock { Set-FSxDedupSchedule -Name "WeeklyGarbageCollection" -Days $Using:DayOfWeek -Start $Using:Time -DurationHours 9 } ``` After the garbage collection job has run and the space has been freed up, set the schedule back to its original settings. ](data-dedup-ts.md#data-dedup-ts.title). For more information about data deduplication, see the Microsoft [Understanding Data Deduplication](https://docs.microsoft.com/en-us/windows-server/storage/data-deduplication/understand) documentation. **Warning** It is not recommended to run certain Robocopy commands with data deduplication because these commands can impact the data integrity of the Chunk Store. For more information, see the Microsoft [Data Deduplication interoperability](https://docs.microsoft.com/en-us/windows-server/storage/data-deduplication/interop) documentation. ### Best practices when using data deduplication Best practices Here are some best practices for using Data Deduplication: + **Schedule Data Deduplication jobs to run when your file system is idle**: The default schedule includes a weekly `GarbageCollection` job at 2:45 UTC on Saturdays. It can take multiple hours to complete if you have a large amount of data churn on your file system. If this time isn't ideal for your workload, schedule this job to run at a time when you expect low traffic on your file system. + **Configure sufficient throughput capacity for Data Deduplication to complete**: Higher throughput capacities provide higher levels of memory. Microsoft recommends having 1 GB of memory per 1 TB of logical data to run Data Deduplication. Use the [Amazon FSx performance table](performance.md#impact-throughput-cap-performance) to determine the memory that's associated with your file system's throughput capacity and ensure that the memory resources are sufficient for the size of your data. + **Customize Data Deduplication settings to meet your specific storage needs and reduce performance requirements**: You can constrain the optimization to run on specific file types or folders, or set a minimum file size and age for optimization. To learn more, see [Reducing storage costs with Data Deduplication](#using-data-dedup). # Managing storage quotas You can configure user storage quotas on your file systems to limit how much data storage that users can consume. After you set quotas, you can track quota status to monitor usage and see when users surpass their quotas. You can also enforce quotas by stopping users who reach their quotas from writing to the storage space. When you enforce quotas, a user that exceeds their quota receives an "insufficient disk space" error message. You can set these thresholds for quota settings: + Warning – used to track whether a user or group is approaching their quota limit, relevant for tracking only. + Limit – the storage quota limit for a user or group. You can configure default quotas that are applied to new users who access a file system and quotas that apply to specific users or groups. You can also view a report of how much storage each user or group is consuming and whether they're surpassing their quotas. Storage consumption at a user level is tracked based on file ownership. Storage consumption is calculated using logical file size, not the actual physical storage space that files occupy. User storage quotas are tracked at the time when data is written to a file. Updating quotas for multiple users requires either running the update command once for each user, or organizing the users into a group and updating the quota for that group. You can manage user storage quotas on your file system using the Amazon FSx CLI for remote management on PowerShell. To learn how to use this CLI, see [Using the Amazon FSx CLI for PowerShell](administering-file-systems.md#remote-pwrshell). Following are commands that you can use to manage user storage quotas. | User storage quotas command | Description | | --- | --- | | **Enable-FSxUserQuotas** | Starts tracking or enforcing user storage quotas, or both. | | **Disable-FSxUserQuotas** | Stops tracking and enforcement for user storage quotas. | | **Get-FSxUserQuotaSettings** | Retrieves the current user-storage quota settings for the file system. | | **Get-FSxUserQuotaEntries** | Retrieves the current user-storage quota entries for individual users and groups on the file system. | | **Set-FSxUserQuotas** | Set the user storage quota for an individual user or group. Quota values are specified in bytes. | The online help for each command provides a reference of all command options. To access this help, run the command with **-?**, for example **Enable-FSxUserQuotas -?**. # Increasing file system storage capacity Increasing storage capacity You can increase your FSx for Windows File Server file system's storage capacity as your storage requirements change. Use the Amazon FSx console, the AWS CLI, or the Amazon FSx API to increase a file system's storage capacity as described in the following procedures. For more information, see [Managing storage capacity](managing-storage-configuration.md#managing-storage-capacity). ## To increase storage capacity for a file system (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 increase storage capacity for. 1. For **Actions**, choose **Update storage**. Or, in the **Summary** panel, choose **Update** next to the file system's **Storage capacity**. The **Update storage capacity** window appears. 1. For **Input type**, choose **Percentage** to enter the new storage capacity as a percentage change from the current value, or choose **Absolute** to enter the new value in GiB. 1. Enter the **Desired storage capacity**. **Note** The desired capacity value must be at least 10 percent larger than the current value, up to the maximum value of 65,536 GiB. 1. Choose **Update** to initiate the storage capacity update. 1. You can monitor the update progress on the **File systems** detail page, in the **Updates** tab. ## To increase storage capacity for a file system (CLI) To increase the storage capacity for an FSx for Windows File Server file system, use the AWS CLI command [update-file-system](https://docs.aws.amazon.com/cli/latest/reference/fsx/update-file-system.html). Set the following parameters: + `--file-system-id` to the ID of the file system you are updating. + `--storage-capacity` to a value that is at least 10 percent greater than the current value. You can monitor the progress of the update by using the AWS CLI command [describe-file-systems](https://docs.aws.amazon.com/cli/latest/reference/fsx/describe-file-systems.html). Look for the `administrative-actions` in the output. For more information, see [AdministrativeAction](https://docs.aws.amazon.com/fsx/latest/APIReference/API_AdministrativeAction.html). # Monitoring storage capacity increases Monitoring storage increases After increasing your file system's storage capacity, you can monitor the progress of the storage capacity increase using the Amazon FSx console, the API, or the AWS CLI as described in the following procedures. ## Monitoring increases in the console In the **Updates** tab in the **File system details** window, you can view the 10 most recent updates for each update type. For storage capacity updates, you can view the following information. ****Update type**** Possible values are **Storage capacity**. ****Target value**** The desired value to update the file system's storage capacity to. ****Status**** The current status of the update. For storage capacity updates, the possible values are as follows: + **Pending** – Amazon FSx has received the update request, but has not started processing it. + **In progress** – Amazon FSx is processing the update request. + **Updated optimizing** – Amazon FSx has increased the file system's storage capacity. The storage optimization process is now moving the file system data to the new larger disks. + **Completed** – The storage capacity increase completed successfully. + **Failed** – The storage capacity increase failed. Choose the question mark (**?**) to see details on why the storage update failed. ****Progress %**** Displays the progress of the storage optimization process as percent complete. ****Request time**** The time that Amazon FSx received the update action request. ## Monitoring increases with the AWS CLI and API You can view and monitor file system storage capacity increase requests using the [describe-file-systems](https://docs.aws.amazon.com/cli/latest/reference/fsx/describe-file-systems.html) AWS CLI command and the [DescribeFileSystems](https://docs.aws.amazon.com/fsx/latest/APIReference/API_DescribeFileSystems.html) API action. The `AdministrativeActions` array lists the 10 most recent update actions for each administrative action type. When you increase a file system's storage capacity, two `AdministrativeActions` are generated: a `FILE_SYSTEM_UPDATE` and a `STORAGE_OPTIMIZATION` action. The following example shows an excerpt of the response of a **describe-file-systems** CLI command. The file system has a storage capacity of 300 GB, and there is a pending administrative action to increase the storage capacity to 1000 GB. ``` { "FileSystems": [ { "OwnerId": "111122223333", . . . "StorageCapacity": 300, "AdministrativeActions": [ { "AdministrativeActionType": "FILE_SYSTEM_UPDATE", "RequestTime": 1581694764.757, "Status": "PENDING", "TargetFileSystemValues": { "StorageCapacity": 1000 } }, { "AdministrativeActionType": "STORAGE_OPTIMIZATION", "RequestTime": 1581694764.757, "Status": "PENDING", } ] ``` Amazon FSx processes the `FILE_SYSTEM_UPDATE` action first, adding the new larger storage disks to the file system. When the new storage is available to the file system, the `FILE_SYSTEM_UPDATE` status changes to `UPDATED_OPTIMIZING`. The storage capacity shows the new larger value, and Amazon FSx begins processing the `STORAGE_OPTIMIZATION` administrative action. This is shown in the following excerpt of the response of a **describe-file-systems** CLI command. The `ProgressPercent` property displays the progress of the storage optimization process. After the storage optimization process completes successfully, the status of the `FILE_SYSTEM_UPDATE` action changes to `COMPLETED`, and the `STORAGE_OPTIMIZATION` action no longer appears. ``` { "FileSystems": [ { "OwnerId": "111122223333", . . . "StorageCapacity": 1000, "AdministrativeActions": [ { "AdministrativeActionType": "FILE_SYSTEM_UPDATE", "RequestTime": 1581694764.757, "Status": "UPDATED_OPTIMIZING", "TargetFileSystemValues": { "StorageCapacity": 1000 } }, { "AdministrativeActionType": "STORAGE_OPTIMIZATION", "RequestTime": 1581694764.757, "Status": "IN_PROGRESS", "ProgressPercent": 50, } ] ``` If the storage capacity increase fails, the status of the `FILE_SYSTEM_UPDATE` action changes to `FAILED`. The `FailureDetails` property provides information about the failure, shown in the following example. ``` { "FileSystems": [ { "OwnerId": "111122223333", . . . "StorageCapacity": 300, "AdministrativeActions": [ { "AdministrativeActionType": "FILE_SYSTEM_UPDATE", "FailureDetails": { "Message": "string" }, "RequestTime": 1581694764.757, "Status": "FAILED", "TargetFileSystemValues": "StorageCapacity": 1000 } ] ``` For information about troubleshooting failed actions, see [Storage or throughput capacity updates fail](admin-actions-ts.md). # Increasing the storage capacity of an FSx for Windows File Server file system dynamically Increasing storage capacity dynamically As an alternative to manually increasing your FSx for Windows File Server file system's storage capacity as the amount of data stored increases, you can use a CloudFormation template to increase storage automatically. The solution presented in the this section dynamically increases a file system's storage capacity when the amount of free storage capacity falls below a defined threshold that you specify. This AWS CloudFormation template automatically deploys all of the components that are required to define the free storage capacity threshold, the Amazon CloudWatch alarm based on this threshold, and the AWS Lambda function that increases the file system’s storage capacity. The solution takes in the following parameters: + The file system ID + The free storage capacity threshold (numerical value) + Unit of measurement (percentage [default] or GiB) + The percentage by which to increase the storage capacity (%) + The email address for the SNS subscription + Adjust alarm threshold (Yes/No) **Topics** + [ ## Architecture overview ](#storage-inc-architecture) + [ ## CloudFormation template ](#storage-capacity-CFN-template) + [ ## Automated deployment with CloudFormation ](#fsx-dynamic-storage-increase-deployment) ## Architecture overview Deploying this solution builds the following resources in the AWS Cloud. ![\[Architecture diagram of the solution to automatically increase the storage capacity of an FSx for Windows File Server file system.\]](http://docs.aws.amazon.com/fsx/latest/WindowsGuide/images/auto-storage-increase-architecture.png) The diagram illustrates the following steps: 1. The CloudFormation template deploys a CloudWatch alarm, an AWS Lambda function, an Amazon Simple Notification Service (Amazon SNS) queue, and all required AWS Identity and Access Management (IAM) roles. The IAM role gives the Lambda function permission to invoke the Amazon FSx API operations. 1. CloudWatch triggers an alarm when the file system’s free storage capacity goes below the specified threshold, and sends a message to the Amazon SNS queue. 1. The solution then triggers the Lambda function that is subscribed to this Amazon SNS topic. 1. The Lambda function calculates the new file system storage capacity based on the specified percent increase value and sets the new file system storage capacity. 1. The Lambda function can optionally adjust the free storage capacity threshold so that it is equal to a specified percentage of the file system’s new storage capacity. 1. The original CloudWatch alarm state and results of the Lambda function operations are sent to the Amazon SNS queue. To receive notifications about the actions that are performed as a response to the CloudWatch alarm, you must confirm the Amazon SNS topic subscription by following the link provided in the **Subscription Confirmation** email. ## CloudFormation template This solution uses CloudFormation to automate deploying the components that are used to automatically increase the storage capacity of an FSx for Windows File Server file system. To use this solution, download the [IncreaseFSxSize](https://s3.amazonaws.com/solution-references/fsx/DynamicScaling/IncreaseFSxSize.yaml) CloudFormation template. The template uses the **Parameters** described as follows. Review the template parameters and their default values, and modify them for the needs of your file system. **FileSystemId** No default value. The ID of the file system for which you want to automatically increase the storage capacity. **LowFreeDataStorageCapacityThreshold** No default value. Specifies the initial free storage capacity threshold at which to trigger an alarm and automatically increase the file system's storage capacity, specified in GiB or as a percentage (%) of the file system's current storage capacity. When expressed as a percentage, the CloudFormation template re-calculates to GiB to match the CloudWatch alarm settings. **LowFreeDataStorageCapacityThresholdUnit** Default is **%**. Specifies the units for the `LowFreeDataStorageCapacityThreshold`, either in GiB or as a percentage of the current storage capacity. **AlarmModificationNotification** Default is **Yes**. If set to Yes, the initial `LowFreeDataStorageCapacityThreshold`, is increased proportionally to the value of `PercentIncrease` for subsequent alarm thresholds. For example, when `PercentIncrease` is set to 20, and AlarmModificationNotification is set to Yes, the available free space threshold (`LowFreeDataStorageCapacityThreshold`) specified in GiB is increased by 20% for subsequent storage capacity increase events. **EmailAddress** No default value. Specifies the email address to use for the SNS subscription and receives storage capacity threshold alerts. **PercentIncrease** No default value. Specifies the amount by which to increase the storage capacity, expressed as a percentage of the current storage capacity. ## Automated deployment with CloudFormation The following procedure configures and deploys an CloudFormation stack to automatically increase the storage capacity of an FSx for Windows File Server file system. It takes about 5 minutes to deploy. **Note** Implementing this solution incurs billing for the associated AWS services. For more information, see the pricing details pages for those services. Before you start, you must have the ID of the Amazon FSx file system running in an Amazon Virtual Private Cloud (Amazon VPC) in your AWS account. For more information about creating Amazon FSx resources, see [Getting started with Amazon FSx for Windows File Server](getting-started.md). **To launch the automatic storage capacity increase solution stack** 1. Download the [IncreaseFSxSize](https://s3.amazonaws.com/solution-references/fsx/DynamicScaling/IncreaseFSxSize.yaml) CloudFormation template. For more information about creating a CloudFormation stack, see [Creating a stack on the AWS CloudFormation console](https://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/cfn-console-create-stack.html) in the *AWS CloudFormation User Guide*. **Note** Amazon FSx is currently only available in specific AWS Regions. You must launch this solution in an AWS Region where Amazon FSx is available. For more information, see [Amazon FSx endpoints and quotas](https://docs.aws.amazon.com/general/latest/gr/fsxn.html) in the *AWS General Reference*. 1. In **Specify stack details**, enter the values for your automatic storage capacity increase solution. ![\[Screenshot showing the values entered for the Specify stack details page for the CloudFormation template.\]](http://docs.aws.amazon.com/fsx/latest/WindowsGuide/images/dynamic-storage-capacity-increase-cfn-stack.png) 1. Enter a **Stack name**. 1. For **Parameters**, review the parameters for the template and modify them for the needs of your file system. Then choose **Next**. 1. Enter any **Options** settings that you want for your custom solution, and then choose **Next**. 1. For **Review**, review and confirm the solution settings. You must select the check box acknowledging that the template creates IAM resources. 1. Choose **Create** to deploy the stack. You can view the status of the stack in the CloudFormation console in the **Status** column. You should see a status of **CREATE\$1COMPLETE** in about 5 minutes. ### Updating the stack After the stack is created, you can update it by using the same template and providing new values for the parameters. For more information, see [Updating stacks directly](https://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/using-cfn-updating-stacks-direct.html) in the *AWS CloudFormation User Guide*. # Updating the storage type of a FSx for Windows file system Updating storage type You can change the storage type of a file system that uses HDD storage to use SSD storage. You can use the the Amazon FSx console, the AWS CLI, or the Amazon FSx API to change a file system's storage type, as shown in the following procedures. For more information, see [Managing your file system's storage type](managing-storage-configuration.md#managing-storage-type). ## To update a file system's storage type (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 update the storage type for. 1. Under **Actions**, choose **Update storage type**. Or, in the **Summary** panel, select the **Update** button next to **HDD**. The **Update storage type** window appears. 1. For **Desired storage type**, choose **SSD**. Choose **Update** to initiate the storage type update. You can [monitor the progress](monitoring-storage-type-updates.md) of the storage type update using the console and the CLI. ## To update a file system's storage type (CLI) To update storage type for an FSx for Windows File Server file system, use the AWS CLI command [update-file-system](https://docs.aws.amazon.com/cli/latest/reference/fsx/update-file-system.html). Set the following parameters: + `--file-system-id` to the ID of the file system that you want to update. + `--storage-type` to SSD. You can't switch from SSD storage type to HDD storage type. You can monitor the progress of the update by using the AWS CLI command [describe-file-systems](https://docs.aws.amazon.com/cli/latest/reference/fsx/describe-file-systems.html). Look for the `administrative-actions` in the output. For more information, see [AdministrativeAction](https://docs.aws.amazon.com/fsx/latest/APIReference/API_AdministrativeAction.html). # Monitoring storage type updates After you update your file system's storage type from HDD to SSD storage, you can monitor the progress of the storage type update using the Amazon FSx console, the AWS CLI, or the API, as described in the following procedures. ## Monitoring file system updates in the console On the **Updates** tab in the **File system details** window, you can view the 10 most recent updates for each update type. For storage type updates, you can view the following information. ****Update type**** Possible value is **Storage type**. ****Target value**** **SSD** ****Status**** The current status of the update. For storage type updates, the possible values are as follows: + **Pending** – Amazon FSx received the update request, but has not started processing it. + **In progress** – Amazon FSx is processing the update request. + **Updated optimizing** – The SSD storage performance is available for write operations. The update enters an **Updated optimizing** state, which typically lasts a few hours, during which read operations will have performance levels between HDD and SSD. Once your update action is complete, your new SSD performance is available for both reads and writes. + **Completed** – The storage type update completed successfully. + **Failed** – The storage type update failed. Choose the question mark (**?**) to see details. ****Progress %**** Displays the progress of the storage optimization process by the percentage that's complete. ****Request time**** The time that Amazon FSx received the update action request. ## Monitoring updates with the AWS CLI and API You can view and monitor file system storage type update requests using the [describe-file-systems](https://docs.aws.amazon.com/cli/latest/reference/fsx/describe-file-systems.html) AWS CLI command and the [DescribeFileSystems](https://docs.aws.amazon.com/fsx/latest/APIReference/API_DescribeFileSystems.html) API action. The `AdministrativeActions` array lists the 10 most recent update actions for each administrative action type. When you increase a file system's SSD IOPS, two `AdministrativeActions` are generated: a `FILE_SYSTEM_UPDATE` and a `STORAGE_TYPE_OPTIMIZATION` action. # Updating a file system's SSD IOPS Updating the SSD IOPS For file systems configured with SSD storage, the level of provisioned SSD IOPS determines the amount of disk I/O available when your file system has to read data from and write data to disk, as opposed to reading or writing data that is in cache. You can update SSD IOPS for a file system using the Amazon FSx console, the AWS CLI, or the Amazon FSx API, as described in the following procedures. For more information about managing SSD IOPS, see [Managing SSD IOPS](managing-storage-configuration.md#managing-provisioned-ssd-iops). ## To update SSD IOPS for a file system (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 update SSD IOPS for. 1. Under **Actions**, choose **Update SSD IOPS**. Or, in the **Summary** panel, select the **Update** button next to **Provisioned SSD IOPS**. The **Update IOPS provisioning** window opens. 1. For **Mode**, choose **Automatic** or **User-provisioned**. If you choose **Automatic**, Amazon FSx automatically provisions 3 SSD IOPS per GiB of storage capacity for your file system. If you choose **User-provisioned**, enter any whole number in the range of 96–400,000. 1. Choose **Update** to initiate the provisioned SSD IOPS update. 1. You can monitor the update progress on the **File systems** detail page, on the **Updates** tab. ## To update SSD IOPS for a file system (CLI) To update SSD IOPS for an FSx for Windows File Server file system, use the `--windows-configuration DiskIopsConfiguration` property. This property has two parameters, `Iops` and `Mode`: + If you want to specify the number of SSD IOPS, use `Iops=number_of_IOPS`, up to a maximum of 400,000 in supported AWS Regions and `Mode=USER_PROVISIONED`. + If you want Amazon FSx to increase your SSD IOPS automatically, use `Mode=AUTOMATIC` and don't use the `Iops` parameter. Amazon FSx automatically maintains 3 SSD IOPS per GiB of storage capacity on your file system, up to a maximum of 400,000 in supported AWS Regions. You can monitor the progress of the update by using the AWS CLI command [describe-file-systems](https://docs.aws.amazon.com/cli/latest/reference/fsx/describe-file-systems.html). Look for the `administrative-actions` in the output. For more information, see [AdministrativeAction](https://docs.aws.amazon.com/fsx/latest/APIReference/API_AdministrativeAction.html). # Monitoring provisioned SSD IOPS updates After you update the amount of provisioned SSD IOPS for your file system, you can monitor the progress of the SSD IOPS update using the Amazon FSx console, the AWS CLI, and the API, as described in the following procedures. ## Monitoring updates in the console In the **Updates** tab in the **File system details** window, you can view the 10 most recent updates for each update type. For provisioned SSD IOPS updates, you can view the following information. ****Update type**** Possible values are **IOPS Mode** and **SSD IOPS**. ****Target value**** The desired value to update the file system's IOPS mode and SSD IOPS to. ****Status**** The current status of the update. For SSD IOPS updates, the possible values are as follows: + **Pending** – Amazon FSx has received the update request, but has not started processing it. + **In progress** – Amazon FSx is processing the update request. + **Updated optimizing** – The new IOPS level is available for your workload's write operations. Your update enters an **Updated optimizing** state, which typically lasts a few hours, during which your workload's read operations have IOPS performance between the previous level and the new level. After your update action is complete, your new IOPS level is available for both reads and writes. + **Completed** – The SSD IOPS update completed successfully. + **Failed** – The SSD IOPS update failed. Choose the question mark (**?**) to see details on why the storage update failed. ****Progress %**** Displays the progress of the storage optimization process as percent complete. ****Request time**** The time that Amazon FSx received the update action request. ## Monitoring updates with the AWS CLI and API You can view and monitor file system SSD IOPS update requests using the [describe-file-systems](https://docs.aws.amazon.com/cli/latest/reference/fsx/describe-file-systems.html) AWS CLI command and the [DescribeFileSystems](https://docs.aws.amazon.com/fsx/latest/APIReference/API_DescribeFileSystems.html) API action. The `AdministrativeActions` array lists the 10 most recent update actions for each administrative action type. When you increase a file system's SSD IOPS, two `AdministrativeActions` are generated: a `FILE_SYSTEM_UPDATE` and an `IOPS_OPTIMIZATION` action. # Managing data deduplication You can manage your file system's [data deduplication settings](managing-storage-configuration.md#using-data-dedup) using the Amazon FSx CLI for remote management on PowerShell. For more information about using the Amazon FSx CLI remote management on PowerShell, see [Using the Amazon FSx CLI for PowerShell](administering-file-systems.md#remote-pwrshell). Following are commands that you can use for data deduplication. | Data deduplication command | Description | | --- | --- | | **[Enable-FSxDedup](#enable-dedup)** | Enables data deduplication on the file share. Data compression after deduplication is enabled by default when you enable data deduplication. | | **Disable-FSxDedup** | Disables data deduplication on the file share. | | **Get-FSxDedupConfiguration** | Retrieves deduplication configuration information, including Minimum file size and age for optimization, compression settings, and Excluded file types and folders. | | **Set-FSxDedupConfiguration** | Changes the deduplication configuration settings, including minimum file size and age for optimization, compression settings, and excluded file types and folders. | | **[Get-FSxDedupStatus](#get-dedup-status)** | Retrieve the deduplication status, and include read-only properties that describe optimization savings and status on the file system, times, and completion status for the last dedup jobs on the file system. | | **Get-FSxDedupMetadata** | Retrieves deduplication optimization metadata. | | **Update-FSxDedupStatus** | Computes and retrieves updated data deduplication savings information. | | **Measure-FSxDedupFileMetadata** | Measures and retrieves the potential storage space that you can reclaim on your file system if you delete a group of folders. Files often have chunks that are shared across other folders, and the deduplication engine calculates which chunks are unique and would be deleted. | | **Get-FSxDedupSchedule** | Retrieves deduplication schedules that are currently defined. | | **[New-FSxDedupSchedule](#new-dedup-sched)** | Create and customize a data deduplication schedule. | | **[Set-FSxDedupSchedule](#set-dedup-sched)** | Change configuration settings for existing data deduplication schedules. | | **Remove-FSxDedupSchedule** | Delete a deduplication schedule. | | **Get-FSxDedupJob** | Get status and information for all currently running or queued deduplication jobs. | | **Stop-FSxDedupJob** | Cancel one or more specified data deduplication jobs. | The online help for each command provides a reference of all command options. To access this help, run the command with **-?**, for example **Enable-FSxDedup -?**. ## Enabling data deduplication You enable data deduplication on an Amazon FSx for Windows File Server file share using the `Enable-FSxDedup` command, as follows. ``` PS C:\Users\Admin> Invoke-Command -ComputerName amznfsxzzzzzzzz.corp.example.com -ConfigurationName FSxRemoteAdmin -ScriptBlock {Enable-FsxDedup } ``` When you enable data deduplication, a default schedule and configuration are created. You can create, modify, and remove schedules and configurations using the commands below. You can use the `Disable-FSxDedup` command to disable data deduplication entirely on your file system. ## Creating a data deduplication schedule Although the default schedule works well in most cases, you can create a new deduplication schedule by using the `New-FsxDedupSchedule` command, shown as follows. Data deduplication schedules use UTC time. ``` PS C:\Users\Admin> Invoke-Command -ComputerName amznfsxzzzzzzzz.corp.example.com -ConfigurationName FSxRemoteAdmin -ScriptBlock { New-FSxDedupSchedule -Name "CustomOptimization" -Type Optimization -Days Mon,Wed,Sat -Start 08:00 -DurationHours 7 } ``` This command creates a schedule named `CustomOptimization` that runs on days Monday, Wednesday, and Saturday, starting the job at 8:00 am (UTC) each day, with a maximum duration of 7 hours, after which the job stops if it is still running. Note that creating new, custom deduplication job schedules does not override or remove the existing default schedule. Before creating a custom deduplication job, you may want to disable the default job if you don’t need it. You can disable the default deduplication schedule by using the `Set-FsxDedupSchedule` command, shown as follows. ``` PS C:\Users\Admin> Invoke-Command -ComputerName amznfsxzzzzzzzz.corp.example.com -ConfigurationName FSxRemoteAdmin -ScriptBlock {Set-FSxDedupSchedule -Name “BackgroundOptimization” -Enabled $false} ``` You can remove a deduplication schedule by using the `Remove-FSxDedupSchedule -Name "ScheduleName"` command. Note that the default `BackgroundOptimization` deduplication schedule cannot be modified or removed and will need to be disabled instead. ## Modifying a data deduplication schedule You can modify an existing deduplication schedule by using the `Set-FsxDedupSchedule` command, shown as follows. ``` PS C:\Users\Admin> Invoke-Command -ComputerName amznfsxzzzzzzzz.corp.example.com -ConfigurationName FSxRemoteAdmin -ScriptBlock { Set-FSxDedupSchedule -Name "CustomOptimization" -Type Optimization -Days Mon,Tues,Wed,Sat -Start 09:00 -DurationHours 9 } ``` This command modifies the existing `CustomOptimization` schedule to run on days Monday to Wednesday and Saturday, starting the job at 9:00 am (UTC) each day, with a maximum duration of 9 hours, after which the job stops if it is still running. To modify the minimum file age before optimizing setting, use the `Set-FSxDedupConfiguration` command. ## Viewing the amount of saved space To view the amount of disk space you are saving from running data deduplication, use the `Get-FSxDedupStatus` command, as follows. ``` PS C:\Users\Admin> Invoke-Command -ComputerName amznfsxzzzzzzzz.corp.example.com -ConfigurationName FsxRemoteAdmin -ScriptBlock { Get-FSxDedupStatus } | select OptimizedFilesCount,OptimizedFilesSize,SavedSpace,OptimizedFilesSavingsRate OptimizedFilesCount OptimizedFilesSize SavedSpace OptimizedFilesSavingsRate ------------------- ------------------ ---------- ------------------------- 12587 31163594 25944826 83 ``` **Note** The values shown in the command response for following parameters are not reliable, and you should not use these values: Capacity, FreeSpace, UsedSpace, UnoptimizedSize, and SavingsRate. # Troubleshooting data deduplication Use the following information to help troubleshoot some common issues when configuring and using data deduplication. **Topics** + [ ## Data deduplication is not working ](#data-dedup-not-working) + [ ## Deduplication values are unexpectedly set to 0 ](#data-dedup-stopped) + [ ## Space is not freed up on file system after deleting files ](#data-dedup-freed-space) ## Data deduplication is not working To see the current status of data deduplication, run the `Get-FSxDedupStatus` PowerShell command to view the completion status for the most recent deduplication jobs. If one or more jobs is failing, you may not see an increase in free storage capacity on your file system. The most common reason for deduplication jobs failing is insufficient memory. + Microsoft [recommends](https://docs.microsoft.com/en-us/windows-server/storage/data-deduplication/install-enable#faq) optimally having 1 GB of memory per 1 TB of logical data (or at a minimum 350 MB per 1 TB of logical data). Use the [Amazon FSx performance table](performance.md#performance-table) to determine the memory associated with your file system's throughput capacity and ensure the memory resources are sufficient for the size of your data. If it is not, you need to [increase the file system's throughput capacity](managing-throughput-capacity.md) to the level that meets the memory requirements of 1 GB per 1 TB of logical data. + Deduplication jobs are configured with the Windows recommended default of 25% memory allocation, which means that for a file system with 32 GB of memory, 8 GB will be available for deduplication. The memory allocation is configurable (using the `Set-FSxDedupSchedule` command with parameter `–Memory`). Be aware that using a higher memory allocation for dedup may impact file system performance. + You can modify the configuration of deduplication jobs to reduce the amount of memory required. For example, you can constrain the optimization to run on specific file types or folders, or set a minimum file size and age for optimization. We also recommend configuring deduplication jobs to run during idle periods when there is minimal load on your file system. You may also see errors if deduplication jobs have insufficient time to complete. You may need to change the maximum duration of jobs, as described in [Modifying a data deduplication schedule](managing-data-dedup.md#set-dedup-sched). If deduplication jobs have been failing for a long period of time, and there have been changes to the data on the file system during this period, subsequent deduplication jobs may require more resources to complete successfully for the first time. ## Deduplication values are unexpectedly set to 0 The values for `SavedSpace` and `OptimizedFilesSavingsRate` are unexpectedly 0 for a file system on which you have configured data deduplication. This can occur during the storage optimization process when you increase the file system's storage capacity. When you increase a file system's storage capacity, Amazon FSx cancels existing data deduplication jobs during the storage optimization process, which migrates data from the old disks to the new, larger disks. Amazon FSx resumes data deduplication on the file system once the storage optimization job completes. For more information about increasing storage capacity and storage optimization, see [Managing storage capacity](managing-storage-configuration.md#managing-storage-capacity). ## Space is not freed up on file system after deleting files The expected behavior of data deduplication is that if the data that was deleted was something that dedup had saved space on, then the space is not actually freed up on your file system until the garbage collection job runs. A practice you may find helpful is to set the schedule to run the garbage collection job right after you delete a large number of files. After the garbage collection job finishes, you can set the garbage collection schedule back to its original settings. This ensures you can quickly see the space from your deletions immediately. Use the following procedure to set the garbage collection job to run in 5 minutes. 1. To verify that data deduplication is enabled, use the `Get-FSxDedupStatus` command. For more information on the command and its expected output, see [Viewing the amount of saved space](managing-data-dedup.md#get-dedup-status). 1. Use the following to set the schedule to run the garbage collection job 5 minutes from now. ``` $FiveMinutesFromNowUTC = ((get-date).AddMinutes(5)).ToUniversalTime() $DayOfWeek = $FiveMinutesFromNowUTC.DayOfWeek $Time = $FiveMinutesFromNowUTC.ToString("HH:mm") Invoke-Command -ComputerName ${RPS_ENDPOINT} -ConfigurationName FSxRemoteAdmin -ScriptBlock { Set-FSxDedupSchedule -Name "WeeklyGarbageCollection" -Days $Using:DayOfWeek -Start $Using:Time -DurationHours 9 } ``` 1. After the garbage collection job has run and the space has been freed up, set the schedule back to its original settings. # Using DFS Namespaces DFS Namespaces is a Windows Server role service that you use to group shared folders located on different servers into one or more logically structured namespaces. This makes it possible to give users a virtual view of shared folders, where a single path leads to files located on multiple file systems, as shown in the following diagram. In addition to organizing and unifying access to your file shares across multiple file systems, ## Group multiple FSx for Windows File Server file systems with DFS Namespaces Using DFS Namespaces You can use Microsoft's Distributed File System (DFS) Namespaces to group file shares on multiple FSx for Windows File Server file systems into one common folder structure, or namespace. Using DFS Namespaces, you can scale file storage beyond the maximum storage capacity of single file system (64 TiB) for large file datasets—up to hundreds of petabytes. This section shows you how to set up DFS namespaces on multiple FSx for Windows File Server file systems. DFS Namespaces is a Windows Server role service that you use to group shared folders located on different servers into one or more logically structured namespaces. This makes it possible to give users a virtual view of shared folders, where a single path leads to files located on multiple file systems, as shown in the following diagram. In addition to organizing and unifying access to your file shares across multiple file systems, ![\[Diagram displaying the process of creating a single namespace on two namespace servers.\]](http://docs.aws.amazon.com/fsx/latest/WindowsGuide/images/FSx-common-namespace.png) For a step-by-step procedure for grouping FSx for Windows file systems using DFS Namespaces, see [Group multiple file systems under a single namespace](group-fsx-namespace.md). ## Improving performance with shards Amazon FSx for Windows File Server supports the use of the Microsoft Distributed File System (DFS). By using DFS Namespaces, you can scale out performance (both read and write) to serve I/O-intensive workloads by spreading your file data across multiple Amazon FSx file systems. At the same time, you can still present a unified view under a common namespace to your applications. This solution involves dividing your file data into smaller datasets or *shards* and storing them across different file systems. Applications accessing your data from multiple instances can achieve high levels of performance by reading and writing to these shards in parallel. You can use the solution provided in [Sharding data using DFS Namespaces for scale-out performance](scaleout-performance.md) to distribute read/write access to your data uniformly across your data multiple FSx for Windows File Server file systems. # Group multiple file systems under a single namespace Group file systems into one namespace In this procedure, you will create a single domain-based namespace (`example.com\corp`) on two namespace servers, in order to consolidate file shares stored on multiple FSx for Windows file systems (finance, marketing, sales, home\$1directories). You will also set up four file shares under the namespace, each transparently redirecting users to shares hosted on separate FSx for Windows file systems. This enables your users to access file shares using a common namespace instead of having to specify the DNS names for each of the file systems hosting the file shares. **Note** Amazon FSx cannot be added to the root of the DFS share path. **To group multiple file systems into a common DFS namespace** 1. If you don't already have DFS Namespace servers running, you can launch a pair of highly available DFS Namespace servers using the [setup-DFSN-servers.template](https://solution-references.s3.amazonaws.com/fsx/dfs/setup-DFSN-servers.template) CloudFormation template. For more information on creating an CloudFormation stack, see [Creating a Stack on the AWS CloudFormation Console](https://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/cfn-console-create-stack.html) in the *AWS CloudFormation User Guide*. 1. Connect to one of the DFS Namespace servers launched in the previous step as a user in the **AWS Delegated Administrators** group. For more information, see [Connecting to Your Windows Instance](https://docs.aws.amazon.com/AWSEC2/latest/WindowsGuide/connecting_to_windows_instance.html) in the *Amazon EC2 User Guide*. 1. Access the DFS Management Console by opening. Open the **Start** menu and run **dfsmgmt.msc**. This opens the DFS Management GUI tool. 1. Choose **Action** then **New Namespace**, type in the computer name of the first DFS Namespace server you launched for **Server** and choose **Next**. 1. For **Name**, type in the namespace you're creating (for example, **corp**). 1. Choose **Edit Settings** and set the appropriate permissions based on your requirements. Choose **Next**. 1. Leave the default **Domain-based namespace** option selected, leave the **Enable Windows Server 2008 mode** option selected, and choose **Next**. **Note** Windows Server 2008 mode is the latest available option for Namespaces. 1. Review the namespace settings and choose **Create**. 1. With the newly created namespace selected under **Namespaces** in the navigation bar, choose **Action** then **Add Namespace Server**. 1. Type in the computer name of the second DFS Namespace server you launched for **Namespace server**. 1. Choose **Edit Settings**, set the appropriate permissions based on your requirements, and choose **OK**. 1. Open the context (right-click) menu for the namespace you just created, choose **New Folder**, type in the name of the folder (for example, `finance` for **Name**, and choose **OK**. 1. Type in the DNS name of the file share that you want the DFS Namespace folder to point to in UNC format (for example, `\\fs-0123456789abcdef0.example.com\finance`) for **Path to folder target** and choose **OK**. 1. If the share doesn't exist: 1. Choose **Yes** to create it. 1. From the **Create Share** dialog, choose **Browse**. 1. Choose an existing folder, or create a new folder under **D\$1**, and choose **OK**. 1. Set the appropriate share permissions, and choose **OK**. 1. From the **New Folder** dialog, choose **OK**. The new folder will be created under the namespace. 1. Repeat the last four steps for other folders you want to share under the same namespace. # Sharding data using DFS Namespaces for scale-out performance The following procedure guides you through creating a DFS solution on Amazon FSx for scale-out performance. In this example, the data stored in the *corp* namespace is sharded alphabetically. Data files ‘A-F’, ‘G-M’ and ‘N-Z’ are all stored on different file shares. Based on the type of data, I/O size, and I/O access pattern, you should decide how to best shard your data across multiple file shares. Choose a sharding convention that distributes I/O evenly across all the file shares you plan on using. Keep in mind that each namespace supports up to 50,000 file shares and hundreds of petabytes of storage capacity in aggregate. ![\[Diagram showing the configuration of a DFS solution on Amazon FSx for scale-out performance.\]](http://docs.aws.amazon.com/fsx/latest/WindowsGuide/images/FSx-scale-out-performance.png) **To set up DFS Namespaces for scale-out performance** 1. If you don't already have DFS Namespace servers running, you can launch a pair of highly available DFS Namespace servers using the [setup-DFSN-servers.template](https://s3.amazonaws.com/solution-references/fsx/dfs/setup-DFSN-servers.template) CloudFormation template. For more information on creating an CloudFormation stack, see [Creating a Stack on the AWS CloudFormation Console](https://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/cfn-console-create-stack.html) in the *AWS CloudFormation User Guide*. 1. Connect to one of the DFS Namespace servers launched in the previous step as a user in the **AWS Delegated Administrators** group. For more information, see [Connecting to Your Windows Instance](https://docs.aws.amazon.com/AWSEC2/latest/WindowsGuide/connecting_to_windows_instance.html) in the *Amazon EC2 User Guide*. 1. Access the DFS Management Console. Open the **Start** menu and run **dfsmgmt.msc**. This opens the DFS Management GUI tool. 1. Choose **Action** then **New Namespace**, type in the computer name of the first DFS Namespace server you launched for **Server** and choose **Next**. 1. For **Name**, type in the namespace you're creating (for example, **corp**). 1. Choose **Edit Settings** and set the appropriate permissions based on your requirements. Choose **Next**. 1. Leave the default **Domain-based namespace** option selected, leave the **Enable Windows Server 2008 mode** option selected, and choose **Next**. **Note** Windows Server 2008 mode is the latest available option for Namespaces. 1. Review the namespace settings and choose **Create**. 1. With the newly created namespace selected under **Namespaces** in the navigation bar, choose **Action** then **Add Namespace Server**. 1. Type in the computer name of the second DFS Namespace server you launched for **Namespace server**. 1. Choose **Edit Settings**, set the appropriate permissions based on your requirements, and choose **OK**. 1. Open the context (right-click) menu for the namespace you just created, choose **New Folder**, enter the name of the folder for the first shard (for example, `A-F` for **Name**), and choose **Add**. 1. Type in the DNS name of the file share hosting this shard in UNC format (for example, `\\fs-0123456789abcdef0.example.com\A-F`) for **Path to folder target** and choose **OK**. 1. If the share doesn't exist: 1. Choose **Yes** to create it. 1. From the **Create Share** dialog, choose **Browse**. 1. Choose an existing folder, or create a new folder under **D\$1**, and choose **OK**. 1. Set the appropriate share permissions, and choose **OK**. 1. With the folder target now added for the shard, choose **OK**. 1. Repeat the last four steps for other shards you want to add to the same namespace. # Managing throughput capacity You can increase and decrease your file system's throughput capacity to help manage its performance at any time. Throughput capacity is one of the dimensions that determines the speed at which the file server hosting your FSx for Windows File Server file system can serve data. Higher levels of throughput capacity also come with higher levels of I/O operations per second (IOPS) and a larger amount of cache memory on the file server. For more information, see [FSx for Windows File Server performancePerformance](performance.md). **Topics** + [ ## How throughput scaling works ](#how-throughput-scaling-works) + [ ## Knowing when to modify throughput capacity ](#when-to-modify-throughput-capacity) + [ # Modifying throughput capacity ](increase-throughput-capacity.md) + [ # Monitoring throughput capacity updates ](monitoring-throughput-capacity-changes.md) ## How throughput scaling works When you modify your file system's throughput capacity, Amazon FSx switches out the file system's file server to one with more or less throughput behind the scenes. For Multi-AZ file systems, switching to a new file server triggers an automatic failover and failback while Amazon FSx switches out the preferred and secondary file servers. Single-AZ file systems will be unavailable for a few minutes while the file server is switched during throughput capacity scaling. You are billed for the new amount of throughput capacity once it becomes available to your file system. **Note** During a maintenance operation on the back end, system modifications (including throughput capacity modifications) may be delayed. Maintenance operations can cause system modifications to queue up to be processed. For Multi-AZ file systems, throughput capacity scaling results in an automatic failover and failback while Amazon FSx switches out the preferred and secondary file servers. During file server replacements, which happen during throughput capacity scaling as well as file system maintenance and an unplanned service disruption, any ongoing traffic to the file system will be served by the remaining file server. When the replaced file server is back online, FSx for Windows will run a resynchronization job to ensure that data is synced back to the newly replaced file server. FSx for Windows is designed to minimize the impact of this resynchronization activity on application and users. However, the resynchronization process involves synchronizing data in large blocks. This means that a large block of data can require synchronization even if only a small portion is updated. Consequently, the amount of resynchronization depends not only on the amount of data churn, but also the nature of the data churn on the file system. If your workload is write-heavy and IOPS-heavy, the data synchronization process may take longer and require additional performance resources. Your file system will continue to be available during this time, but in order to reduce the duration of data synchronization, we recommend modifying throughput capacity during idle periods when there is minimal load on your file system. We also recommend ensuring that your file system has sufficient throughput capacity to run the synchronization job in addition to your workload, in order to reduce the duration of data synchronization. Lastly, we recommend testing the impact of failovers while your file system has a lighter load. ## Knowing when to modify throughput capacity Amazon FSx integrates with Amazon CloudWatch, enabling you to monitor your file system's ongoing throughput usage levels. The performance (throughput and IOPS) that you can drive through your file system depends on your specific workload’s characteristics, along with your file system’s throughput capacity, storage capacity, and storage type. You can use CloudWatch metrics to determine which of these dimensions to change to improve performance. For more information, see [Monitoring with Amazon CloudWatch](monitoring-cloudwatch.md). FSx for Windows File Server provides performance alerts based on values of CloudWatch metrics for your file system in the Monitoring & performance dashboard in the File system details page on the Amazon FSx console. This includes throughput capacity, and other file system metrics that can benefit from throughput capacity increases. For more information, see [Performance warnings and recommendations](monitoring-cloudwatch.md#performance-insights-FSxW). Configure your file system with sufficient throughput capacity to meet not only the expected traffic of your workload, but also additional performance resources that are needed to support the features you enable on your file system. For example, if you’re running data deduplication, the throughput capacity that you select must provide enough memory to run deduplication based on the storage that you have. If you’re using shadow copies, increase throughput capacity to a value that's at least three times the value that's expected to be driven by your workload to avoid Windows Server deleting your shadow copies. For more information, see [Impact of throughput capacity on performance](performance.md#impact-throughput-cap-performance). # Modifying throughput capacity You can increase or decrease your file system's throughput capacity using the Amazon FSx console, the AWS Command Line Interface (AWS CLI), or the Amazon FSx API, as described in the following procedures. ## To modify a file system's throughput capacity (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 increase the throughput capacity for. 1. For **Actions**, choose **Update throughput**. Or, in the **Summary** panel, choose **Update** next to the file system's **Throughput capacity**. The **Update throughput capacity** window appears. 1. Choose the new value for **Throughput capacity** from the list. 1. Choose **Update** to initiate the throughput capacity update. **Note** Multi-AZ file systems fail over and fail back when updating throughput scaling, and are fully available. Single-AZ file systems experience a very brief period of unavailability during the update. 1. You can monitor the update progress on the **File systems** detail page, in the **Updates** tab. You can monitor the progress of the update by using the Amazon FSx console, the AWS CLI, and the API. For more information, see [Monitoring throughput capacity updates](monitoring-throughput-capacity-changes.md). ## To modify a file system's throughput capacity (CLI) To increase or decrease a file system's throughput capacity, use the AWS CLI command [update-file-system](https://docs.aws.amazon.com/cli/latest/reference/fsx/update-file-system.html). Set the following parameters: + `--file-system-id` to the ID of the file system that you are updating. + `ThroughputCapacity` to the desired value; valid values are 8, 16, 32, 64, 128, 256, 512, 1024, 2048, 4608, 6144, 9216, 12288 MBps. You can monitor the progress of the update by using the Amazon FSx console, the AWS CLI, and the API. For more information, see [Monitoring throughput capacity updates](monitoring-throughput-capacity-changes.md). # Monitoring throughput capacity updates You can monitor the progress of a throughput capacity modification using the Amazon FSx console, the API, and the AWS CLI. ## Monitoring throughput capacity changes in the console In the **Updates** tab in the **File system details** window, you can view the 10 most recent update actions for each update action type. ![\[Console screen shot showing the file system updates window.\]](http://docs.aws.amazon.com/fsx/latest/WindowsGuide/images/fs-updates-panel.png) For throughput capacity update actions, you can view the following information. ****Update type**** Possible value is **Throughput capacity**. ****Target value**** The desired value to change the file system's throughput capacity to. ****Status**** The current status of the update. For throughput capacity updates, the possible values are as follows: + **Pending** – Amazon FSx has received the update request, but has not started processing it. + **In progress** – Amazon FSx is processing the update request. + **Updated optimizing** – Amazon FSx has updated the file system's network I/O, CPU, and memory resources. The new disk I/O performance level is available for write operations. Your read operations will see disk I/O performance between the previous level and the new level until your file system is no longer in the this state. + **Completed** – The throughput capacity update completed successfully. + **Failed** – The throughput capacity update failed. Choose the question mark (**?**) to see details on why the throughput update failed. ****Request time**** The time that Amazon FSx received the update request. ## Monitoring changes with the AWS CLI and API You can view and monitor file system throughput capacity modification requests using the [describe-file-systems](https://docs.aws.amazon.com/cli/latest/reference/fsx/describe-file-systems.html) CLI command and the [DescribeFileSystems](https://docs.aws.amazon.com/fsx/latest/APIReference/API_DescribeFileSystems.html) API action. The `AdministrativeActions` array lists the 10 most recent update actions for each administrative action type. When you modify a file system's throughput capacity, a `FILE_SYSTEM_UPDATE` administrative action is generated. The following example shows the response excerpt of a `describe-file-systems` CLI command. The file system has a throughput capacity of 8 MBps, and the target throughput capacity of 256 MBps. ``` . . . "ThroughputCapacity": 8, "AdministrativeActions": [ { "AdministrativeActionType": "FILE_SYSTEM_UPDATE", "RequestTime": 1581694764.757, "Status": "PENDING", "TargetFileSystemValues": { "WindowsConfiguration": { "ThroughputCapacity": 256 } } } ] ``` When Amazon FSx completes processing the action successfully, the status changes to `COMPLETED`. The new throughput capacity is then available to the file system, and shows in the `ThroughputCapacity` property. This is shown in the following response excerpt of a **describe-file-systems** CLI command. ``` . . . "ThroughputCapacity": 256, "AdministrativeActions": [ { "AdministrativeActionType": "FILE_SYSTEM_UPDATE", "RequestTime": 1581694764.757, "Status": "COMPLETED", "TargetFileSystemValues": { "WindowsConfiguration": { "ThroughputCapacity": 256 } } } ] ``` If the throughput capacity modification fails, the status changes to `FAILED`, and the `FailureDetails` property provides information about the failure. For information about troubleshooting failed actions, see [Storage or throughput capacity updates fail](admin-actions-ts.md). # Managing network type Managing network type When you create an FSx for Windows file system, you must specify a network type, which must be one of the following options: + `IPv4` allows your file system to communicate using only Internet Protocol version 4 (IPv4). + `Dual-stack` allows your file system to communicate using both Internet Protocol version 6 (IPv6) and IPv4. You can change the network type of an existing FSx for Windows file system at any time using the Amazon FSx Management Console, AWS CLI, AWS API, or one of the AWS SDKs. For example, if your subnets support both IPv4 and IPv6 addressing, you can update your existing file system from IPv4-only to dual-stack mode, You can also update your dual-stack file system to IPv4-only. ## Using dual-stack mode You should use dual-stack mode if you need to access and manage your Amazon FSx file systems natively from IPv6 clients. By configuring your Amazon FSx file system to use dual-stack addressing, you can access your file data from IPv6 clients, as well as IPv4 clients, in the same Amazon VPC, in another AWS account's VPC, or in your on-premises network. For example, with an Amazon FSx file system configured to use dual-stack, you can have existing IPv4 clients and new IPv6 clients accessing your file data stored on your file system. By default, Amazon FSx and Amazon VPC use the IPv4 addressing protocol. So as a prerequisite to using IPv6, you must first assign an Amazon-provided IPv6 Classless Inter-Domain Range (CIDR) block to your VPC and subnets before you can use IPv6 with your Amazon FSx file systems. For information on enabling IPv6 for your VPC, see [Add IPv6 support for your VPC](https://docs.aws.amazon.com/vpc/latest/userguide/vpc-migrate-ipv6-add.html) in the *Amazon Virtual Private Cloud User Guide*. ## Changing network type You can modify a file system's network type using the Amazon FSx console, the AWS Command Line Interface (AWS CLI), or the Amazon FSx API. ### To change a file system's network type (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 FSx for Windows file system that you want to change the network type for. 1. For **Actions**, choose **Update network type**. Or, in the **Network & security** panel, choose **Manage** next to the file system's **Network type**. The **Update network type** window appears. 1. For **Desired network type**, choose either **IPv4** or **Dual-stack**. + If you choose `IPv4`, no further configuration is required. + If you choose `Dual-stack`, specify the IPv6 address range that your file system endpoints will use: + **Unallocated IPv6 address range from your VPC** – Amazon FSx chooses an available /118 IP address range from one of the VPC's IPv6 CIDR ranges to use as the endpoint IPv6 address range for the file system. 1. Choose **Update**. ### To modify a file system's network type (CLI) + To modify a file system's network type, use the [update-file-system](https://docs.aws.amazon.com/cli/latest/reference/fsx/update-file-system.html) CLI command (or the equivalent [UpdateFileSystem](https://docs.aws.amazon.com/fsx/latest/APIReference/API_UpdateFileSystem.html) API operation), as shown in the following example. ``` aws fsx update-file-system \ --file-system-id fs-0123456789abcdef0 \ --network-type DUAL ``` # Tagging your Amazon FSx resources Tagging resources To help you manage your file systems and other FSx for Windows File Server resources, you can assign your own metadata to each resource in the form of tags. Tags enable you to categorize your AWS resources in different ways, for example, by purpose, owner, or environment. This is useful when you have many resources of the same type—you can quickly identify a specific resource based on the tags that you've assigned to it. This topic describes tags and shows you how to create them. **Topics** + [ ## Tag basics ](#tag-basics) + [ ## Tagging your resources ](#tagging-your-resources) + [ ## Tag restrictions ](#tag-restrictions) + [ ## Permissions required to tag resources ](#tags-iam) ## Tag basics A tag is a label that you assign to an AWS resource. Each tag consists of a key and an optional value, both of which you define. Tags enable you to categorize your AWS resources in different ways, for example, by purpose, owner, or environment. For example, you could define a set of tags for your account's FSx for Windows File Server file systems that helps you track each instance's owner and stack level. We recommend that you devise a set of tag keys that meets your needs for each resource type. Using a consistent set of tag keys makes it easier for you to manage your resources. You can search and filter the resources based on the tags you add. For more information about how to implement an effective resource tagging strategy, see the AWS whitepaper [Tagging Best Practices](https://docs.aws.amazon.com/whitepapers/latest/tagging-best-practices/welcome.html). Tags don't have any semantic meaning to Amazon FSx and are interpreted strictly as a string of characters. Also, tags are not automatically assigned to your resources. You can edit tag keys and values, and you can remove tags from a resource at any time. You can set the value of a tag to an empty string, but you can't set the value of a tag to null. If you add a tag that has the same key as an existing tag on that resource, the new value overwrites the old value. If you delete a resource, any tags for the resource are also deleted. If you're using the FSx for Windows File Server API, the AWS CLI, or an AWS SDK, you can use the `TagResource` API action to apply tags to existing resources. Additionally, some resource-creating actions enable you to specify tags for a resource when the resource is created. If tags cannot be applied during resource creation, we roll back the resource creation process. This ensures that resources are either created with tags or not created at all, and that no resources are left untagged at any time. By tagging resources at the time of creation, you can eliminate the need to run custom tagging scripts after resource creation. For more information about enabling users to tag resources on creation, see [Grant permission to tag resources during creation](using-tags-fsx.md#supported-iam-actions-tagging). ## Tagging your resources You can tag FSx for Windows File Server resources that exist in your account. If you're using the Amazon FSx console, you can apply tags to resources by using the Tags tab on the relevant resource screen. When you create resources, you can apply the Name key with a value, and you can apply tags of your choice when creating a new file system. The console may organize resources according to the Name tag, but this tag doesn't have any semantic meaning to the FSx for Windows File Server service. You can apply tag-based resource-level permissions in your IAM policies to the FSx for Windows File Server API actions that support tagging on creation to implement granular control over the users and groups that can tag resources on creation. Your resources are properly secured from creation—tags are applied immediately to your resources, therefore any tag-based resource-level permissions controlling the use of resources are immediately effective. Your resources can be tracked and reported on more accurately. You can enforce the use of tagging on new resources, and control which tag keys and values are set on your resources. You can also apply resource-level permissions to the `TagResource` and `UntagResource` FSx for Windows File Server API actions in your IAM policies to control which tag keys and values are set on your existing resources. For more information about tagging your resources for billing, see [Using cost allocation tags](https://docs.aws.amazon.com/awsaccountbilling/latest/aboutv2/cost-alloc-tags.html) in the *AWS Billing User Guide*. ## Tag restrictions The following basic restrictions apply to tags: + Maximum number of tags per resource – 50 + For each resource, each tag key must be unique, and each tag key can have only one value. + Maximum key length – 128 Unicode characters in UTF-8 + Maximum value length – 256 Unicode characters in UTF-8 + The allowed characters for FSx for Windows File Server tags are: letters, numbers, and spaces representable in UTF-8, and the following characters: \$1 - = . \$1 : / @. + Tag keys and values are case-sensitive. + The `aws:` prefix is reserved for AWS use. If a tag has a tag key with this prefix, then you can't edit or delete the tag's key or value. Tags with the `aws:` prefix do not count against your tags per resource limit. You can't delete a resource based solely on its tags; you must specify the resource identifier. For example, to delete a file system that you tagged with a tag key called `DeleteMe`, you must use the `DeleteFileSystem` action with the file system resource identifier, such as fs-1234567890abcdef0. When you tag public or shared resources, the tags you assign are available only to your AWS account; no other AWS account will have access to those tags. For tag-based access control to shared resources, each AWS account must assign its own set of tags to control access to the resource. ## Permissions required to tag resources For more information about the permissions required to tag Amazon FSx resources at creation, see [Grant permission to tag resources during creation](using-tags-fsx.md#supported-iam-actions-tagging). For more information about using tags to restrict access to Amazon FSx resources in IAM policies, see [Using tags to control access to your Amazon FSx resources](using-tags-fsx.md#restrict-fsx-access-tags). # Update a file system using the AWS CLI There are three elements that you can update using the procedures in this walkthrough. All other elements of your file system that you can update, you can do so from the console. These procedures assume you have the AWS CLI installed and configured on your local computer. For more information, see [Install](https://docs.aws.amazon.com/cli/latest/userguide/installing.html) and [Configure](https://docs.aws.amazon.com/cli/latest/userguide/cli-chap-getting-started.html) in the *AWS Command Line Interface User Guide*. + **AutomaticBackupRetentionDays** – the number of days that you want to retain automatic backups for your file system. + **DailyAutomaticBackupStartTime** – the time of the day in Coordinated Universal Time (UTC) that you want the daily automatic backup window to start. The window is 30 minutes starting from this specified time. This window can't overlap with the weekly maintenance backup window. + **WeeklyMaintenanceStartTime** – the time of the week that you want the maintenance window to start. Day 1 is Monday, 2 is Tuesday, and so on. The window is 30 minutes starting from this specified time. This window can't overlap with the daily automatic backup window. The following procedures outlines how to update your file system with the AWS CLI. **To update how long automatic backups are retained for your file system** 1. Open a command prompt or terminal on your computer. 1. Run the following command, replacing the file system ID with the ID for your file system, and the number of days that you want to retain your automatic backups for. ``` aws fsx update-file-system --file-system-id fs-0123456789abcdef0 --windows-configuration AutomaticBackupRetentionDays=30 ``` **To update the daily backup window of your file system** 1. Open a command prompt or terminal on your computer. 1. Run the following command, replacing the file system ID with the ID for your file system, and the time with when you want to begin the window. ``` aws fsx update-file-system --file-system-id fs-0123456789abcdef0 --windows-configuration DailyAutomaticBackupStartTime=01:00 ``` **To update the weekly maintenance window of your file system** 1. Open a command prompt or terminal on your computer. 1. Run the following command, replacing the file system ID with the ID for your file system, and the date and time with when you want to begin the window. ``` aws fsx update-file-system --file-system-id fs-0123456789abcdef0 --windows-configuration WeeklyMaintenanceStartTime=1:01:30 ```