|
|
| (14 intermediate revisions by 5 users not shown) |
| Line 1: |
Line 1: |
| − | <div class="docs-alert-info"><i class="fa fa-info-circle"></i> This page describes a feature available in version 7.7 and above</div>
| + | WHMCS includes settings to control storage for various types of files. |
| | | | |
| − | Storage settings allow storing files outside of your WHMCS installation, reducing web space requirements. Prior to version 7.7, WHMCS only supported local storage. With version 7.7, we have introduced Amazon AWS S3 and compatible services for file storage needs. | + | You can access this feature at '''Configuration (<i class="fa fa-wrench" aria-hidden="true"></i>) > System Settings > Storage Settings''' or, prior to WHMCS 8.0, '''Setup > Storage Settings'''. |
| | | | |
| − | ==How it Works== | + | ==Settings== |
| | | | |
| − | By default files will be stored locally within the WHMCS install. If you upgrade an existing WHMCS install to version 7.7 or later, any custom settings for attachments directory and/or downloads directory will be retained and any files will remain in their existing locations. However you may opt to migrate select file types to Amazon AWS S3 or a compatible service. WHMCS offers automatic migrations of your existing files to and from AWS S3, as well as between AWS S3 locations.
| + | The '''Settings''' tab allows you to select storage locations for: |
| | | | |
| − | ==Configuration==
| + | * '''Client Files''' |
| | + | * '''Downloads''' |
| | + | * '''Email Attachments''' |
| | + | * '''Email Images''' |
| | + | * '''Email Template Attachments''' |
| | + | * '''Knowledgebase Images''' |
| | + | * '''Project Management Files''' |
| | + | * '''Ticket Attachments''' |
| | | | |
| − | To manage your storage settings, navigate to '''Setup > Storage Settings'''. Choose one of the following workflows depending on the desired use case. | + | To change the current storage location, select the desired location from the menu. |
| | | | |
| − | ===Local Storage=== | + | ==Configurations== |
| | | | |
| − | You may desire to migrate files from an existing local storage location to another local directory. To do that: | + | The '''Configurations''' tab lets you test, duplicate, configure, and delete your individual storage locations. You can also add new storage configurations. |
| | | | |
| − | #Click "Configuration" tab
| + | <div class="docs-alert-warning"> |
| − | #In "Add New Configuration" tile, choose "Local Storage" or and click "Add".
| + | Amazon S3™ storage locations '''must''' have the required access credentials. For more information and a list of the required settings for Amazon S3 storage locations, see [[Migrating Between Storage Locations]]. |
| − | #Enter path to the new storage location. The directory must exist and be writable. Click "Save".
| |
| − | #Switch to "Settings" tab.
| |
| − | #Select the new storage location for the file type that you wish to migrate to the new location.
| |
| − | #Most file types can be migrated automatically, and you will be prompted to start migration by clicking "Migrate" button. For smaller scale deployments, migration will take less than a minute, and your files will then be stored at the new location. If the migration cannot be completed immediately, it will be scheduled to run in the background. Until it is completed, the former location will continue to be used. Once all files are migrated to the new location, the setting will automatically switch to the new selection and begin using the new location. Former location will not be automatically cleaned - you may want to clean it manually once you validate that the migration was successful.
| |
| − | #You may choose to cancel an ongoing migration. The present location will then continue to be used. Files migrated to the new location until this point will not be deleted.
| |
| − | #Instead of using automated migration, you may opt to migrate your files manually and switch the relevant file types storage setting at once. This will skip automatic migration and assumes your responsibility for moving the files to the new location. If you elect this path, please note that certain file types may be stored by WHMCS in the same folder (for example, client files, email and ticket attachments as well as project management files will be stored in "attachments" folder). If you decide to move all the files away from that folder, all relevant file types must be switched to the new location.
| |
| − | #If you made a change by mistake, click "Revert Changes" to cancel any changes.
| |
| − | | |
| − | ===AWS S3===
| |
| − | <div class="docs-alert-success"> | |
| − | A [https://help.whmcs.com/m/system/c/281650 step-by-step guide] demonstrating a basic S3 configuration is available in our [https://help.whmcs.com/m/system/c/281650 Guides & Tutorials section].
| |
| | </div> | | </div> |
| | | | |
| − | Once the storage bucket is configured, you may desire to migrate files to an AWS S3 bucket or a compatible service. With presumed familiarity of AWS S3, follow these steps:
| + | For more information, see [[Testing WHMCS]]. |
| − | | |
| − | #Click "Configuration" tab
| |
| − | #In "Add New Configuration" tile, choose "S3" or and click "Add".
| |
| − | #Enter AWS S3 connection details. S3 region must be specified as a code name, e.g. "us-east-1" for "US East (N. Virginia)"
| |
| − | #*To find the region code name for a bucket's region, [https://docs.aws.amazon.com/AmazonRDS/latest/UserGuide/Concepts.RegionsAndAvailabilityZones.html click here] for a list of all available AWS regions and their code names.
| |
| − | #*The "Endpoint URL" is not required if using Amazon AWS S3 service - this field is only required if using a non-Amazon, S3-compatible storage provider.
| |
| − | #*The S3 access credentials must have read and write access to the specified S3 bucket. See below for an example of a suitable policy for the S3 user.
| |
| − | #Click "Save". If the bucket cannot be accessed, an error message will be shown.
| |
| − | #Switch to "Settings" tab.
| |
| − | #Select the new storage location for the file type that you wish to migrate to the new location.
| |
| − | #As with local storage, most file types can be migrated automatically, and you will be prompted to start migration by clicking "Migrate" button.
| |
| − | #*For smaller scale deployments, migration will take less than a minute, and your files will then be stored at the new location.
| |
| − | #*If the migration cannot be completed immediately, it will be scheduled to run in the background. Until it is completed, the former location will continue to be used. Once all files are migrated to the new location, the setting will automatically switch to the new selection and begin using the new location.
| |
| − | #*Former location will not be automatically cleaned - you may want to clean it manually once you validate that the migration was successful.
| |
| − | #You may choose to cancel an ongoing migration. The present location will then continue to be used. Files migrated to the new location until this point will not be deleted.
| |
| − | #Instead of using automated migration, you may opt to migrate your files manually and switch the relevant file types storage setting at once. This will skip automatic migration and assumes your responsibility for moving the files to the new location.
| |
| − | #*If you elect this path, please note that certain file types may be stored by WHMCS in the same folder (for example, client files, email and ticket attachments as well as project management files will be stored in "attachments" folder). If you decide to move all the files away from that local folder, all relevant file types must be switched to the new location.
| |
| − | #If you made a change by mistake, click "Revert Changes" to cancel any changes.
| |
| − | | |
| − | ====Example Security Policy====
| |
| − | Consider using the [https://docs.aws.amazon.com/IAM/latest/UserGuide/access_policies_create.html IAM Policy Generator tool] in the AWS control panel, or the [https://awspolicygen.s3.amazonaws.com/policygen.html public policy generator tool].
| |
| − | For power users, an example AWS S3 policy to be assigned to the S3 user for use with WHMCS storage settings is provided below:
| |
| | | | |
| − | {
| + | ===Existing Storage=== |
| − | "Version": "2012-10-17",
| |
| − | "Statement": [
| |
| − | {
| |
| − | "Sid": "Stmt1111222223333",
| |
| − | "Effect": "Allow",
| |
| − | "Action": [
| |
| − | "s3:ListBucket",
| |
| − | "s3:GetObject",
| |
| − | "s3:GetObjectAcl",
| |
| − | "s3:PutObject",
| |
| − | "s3:PutObjectAcl",
| |
| − | "s3:ReplicateObject",
| |
| − | "s3:DeleteObject"
| |
| − | ],
| |
| − | "Resource": [
| |
| − | "arn:aws:s3:::<BUCKET_NAME>",
| |
| − | "arn:aws:s3:::<BUCKET_NAME>/*"
| |
| − | ]
| |
| − | }
| |
| − | ]
| |
| − | }
| |
| | | | |
| − | '''Note for manual migration only''': files in AWS S3 are stored with a prefix corresponding to the file asset type. For example, a file1.png that is a client file will be stored as /client_files/file1.png. Use the following sub-folder names per file type:
| + | For existing storage locations: |
| | | | |
| − | * Client Files - client_files | + | * Click the play icon to test the storage location. |
| − | * Downloads - downloads
| + | * Click the copy icon to duplicate the storage location. |
| − | * Email Attachments - email_attachments | + | * Click the gear icon to update the storage configuration. |
| − | * Email Template Attachments - template_attachments | + | * Click the X icon to delete the storage location. <div class="docs-alert-warning">You cannot delete storage locations that are currently in use.</div> |
| − | * Project Management Files - pm_files | |
| − | * Ticket Attachments - ticket_attachments
| |
| | | | |
| − | When using automatic migration, you do not have to worry about these prefixes - they are managed automatically.
| + | ===Add New Configuration=== |
| | | | |
| − | ===Migrating Between Two AWS S3 locations===
| + | To add a new storage configuration: |
| | | | |
| − | In addition to Amazon AWS S3, WHMCS supports AWS S3 compatible services such as Ceph. However, automatic migration between two S3 locations is only supported if both locations are kept with the same storage provider.
| + | # Choose a type of storage from the menu and click the + icon. |
| | + | # Enter the requested information. |
| | + | # Click '''Save Changes'''. |
| | | | |
| − | ===Migrating From S3 To Local Storage===
| + | ==Migrating to a New Storage Location== |
| | | | |
| − | This migration can be done the same way as the other migration paths, with the same considerations and expectations equally applicable.
| + | You may want to migrate files from one local storage location to another, or from an existing storage location to an AWS S3 bucket or a compatible service. |
| | | | |
| − | ===General Considerations===
| + | * For more information about migrating your files, see [[Migrating Between Storage Locations]]. |
| − | Please note that "Email Attachments" cannot be automatically migrated (as opposed to email template attachments). These files are uploaded when creating a custom email message, and are of transient nature. To avoid any inconsistencies when switching storage settings for email attachments, it should be sufficient to ensure that no administrator users are in process of composing an email message with attachments. Please note that email template attachments are a separate asset type and can be migrated automatically.
| + | * For steps to troubleshoot '''File Not Found''' errors during migrations, see [[Troubleshooting a File Not Found Error]]. |
To change the current storage location, select the desired location from the menu.
You may want to migrate files from one local storage location to another, or from an existing storage location to an AWS S3 bucket or a compatible service.