|
|
| (8 intermediate revisions by the same user not shown) |
| Line 1: |
Line 1: |
| − | ==Configuration==
| + | WHMCS includes settings to control storage for various types of files. |
| | | | |
| − | To manage your storage settings, navigate to '''Configuration (<i class="fa fa-wrench" aria-hidden="true"></i>) > System Settings > Storage Settings'''. Choose one of the following workflows depending on the desired use case:
| + | 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'''. |
| | | | |
| − | ===Local Storage=== | + | ==Settings== |
| | | | |
| − | To migrate files from an existing local storage location to another local directory:
| + | The '''Settings''' tab allows you to select storage locations for: |
| | | | |
| − | {{LocalStorage}}
| + | * '''Client Files''' |
| | + | * '''Downloads''' |
| | + | * '''Email Attachments''' |
| | + | * '''Email Images''' |
| | + | * '''Email Template Attachments''' |
| | + | * '''Knowledgebase Images''' |
| | + | * '''Project Management Files''' |
| | + | * '''Ticket Attachments''' |
| | | | |
| − | ===AWS S3===
| + | To change the current storage location, select the desired location from the menu. |
| − | <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>
| |
| | | | |
| − | After you configure the storage bucket, you may want to migrate files to an AWS S3 bucket or a compatible service. If you are familiar with AWS S3, follow these steps:
| + | ==Configurations== |
| | | | |
| − | #Click the '''Configuration''' tab.
| + | The '''Configurations''' tab lets you test, duplicate, configure, and delete your individual storage locations. You can also add new storage configurations. |
| − | #In '''Add New Configuration''' tile, choose '''S3''' or and click '''Add'''.
| |
| − | #Enter AWS S3 connection details. You must specify the S3 region by its code name (for example, "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].
| |
| − | #*The system doesn't require the '''Endpoint URL''' if you're using the Amazon AWS S3 service. This field is only required if you are 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 system can't access the bucket, an error message will appear.
| |
| − | #Click on the '''Settings''' tab.
| |
| − | #Select the new storage location for the file type that you wish to migrate to the new location. Like using local storage, the system can migrate most file types automatically. The system will prompt you to start migration by clicking the '''Migrate''' button.
| |
| − | #*For smaller-scale deployments, migration will take less than a minute, and your files will then exist at the new location.
| |
| − | #*If the system can't complete the migration immediately, it will schedule it to run in the background. Until it finishes, the system will continue to use the former location. When the migration is finished, the setting will automatically switch to the new selection and begin using the new location.
| |
| − | #*The system won't automatically remove files from the former location. Do this manually after you verify that the migration was successful.
| |
| | | | |
| − | You may choose to cancel an ongoing migration. If you do, the system will continue to use the present location. Files that the system already migrated to the new location will remain.
| + | <div class="docs-alert-warning"> |
| − | | + | 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]]. |
| − | 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 you will be responsible for moving the files to the new location. If you use this method, note that WHMCS may store certain file types in the same folder (for example, the system will store client files, email and ticket attachments, and project management files in the <tt>attachments</tt> folder). If you decide to move all the files away from that local folder, you must switch all relevant file types to the new location.
| + | </div> |
| − | | |
| − | 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 assign to the S3 user for use with WHMCS storage settings is below: | |
| − | | |
| − | {
| |
| − | "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''': The system stores files in AWS S3 with a prefix corresponding to the file asset type. For example, it will store file1.png, a client file, as /client_files/file1.png. Use the following sub-folder names per file type:
| |
| − | | |
| − | * Client Files — client_files
| |
| − | * Downloads — downloads
| |
| − | * Email Attachments — email_attachments
| |
| − | * Email Template Attachments — template_attachments
| |
| − | * Project Management Files — pm_files
| |
| − | * Ticket Attachments — ticket_attachments
| |
| | | | |
| − | When using automatic migration, you do not have to worry about these prefixes; the system manages them automatically.
| + | For more information, see [[Testing WHMCS]]. |
| | | | |
| − | ===Migrating Between Two AWS S3 locations=== | + | ===Existing Storage=== |
| | | | |
| − | In addition to Amazon AWS S3, WHMCS supports AWS S3 compatible services like Ceph. However, WHMCS only supports automatic migration between two S3 locations if both locations use the same storage provider.
| + | For existing storage locations: |
| | | | |
| − | ===Migrating From S3 To Local Storage=== | + | * Click the play icon to test the storage location. |
| | + | * Click the copy icon to duplicate the storage location. |
| | + | * Click the gear icon to update the storage configuration. |
| | + | * 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> |
| | | | |
| − | You can perform this migration the same way as the other migration paths, with the same considerations and expectations equally applicable.
| + | ===Add New Configuration=== |
| | | | |
| − | ===General Considerations===
| + | To add a new storage configuration: |
| − | Note that the system can't automatically migrate '''Email Attachments''' (as opposed to email template attachments). You upload these files when creating a custom email message, and they are of a 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. Note that email template attachments are a separate asset type that you can migrate automatically.
| |
| | | | |
| − | ===Troubleshooting a File Not Found Error===
| + | # Choose a type of storage from the menu and click the + icon. |
| − | If you experience a '''File not found''' error, this may mean that a file is not present or is not accessible at the expected location. To validate that a file is present in the local storage, check that the file exists and its permissions allow access to the web user. For AWS S3, use AWS (or your compatible storage provider's) console to verify that the file is stored with the indicated key.
| + | # Enter the requested information. |
| | + | # Click '''Save Changes'''. |
| | | | |
| − | A convenient way to confirm storage location accessibility is to use the '''Test Configuration''' feature. To do that, go to '''Configuration (<i class="fa fa-wrench" aria-hidden="true"></i>) > System Settings > Storage Settings''', click '''Configurations''' tab, choose a configuration you want to test, and click the '''Test''' icon. For AWS S3 (or compatible providers) this should also indicate whether there are any issues with the provided Access Key / Access Secret.
| + | ==Migrating to a New Storage Location== |
| | | | |
| − | ===Development/Test Environment===
| + | 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. |
| − | When you use local storage locations and are switching between development (test) or live environments, it's important to update your storage settings. If the configured storage locations are not present on your server, certain features (such as sending emails) may not function correctly.
| |
| | | | |
| − | Please see our documentation on [https://docs.whmcs.com/Moving_Storage_Locations#Local_Storage creating local storage locations] and [https://docs.whmcs.com/Moving_Storage_Locations#Migrate_to_new_Storage_Locations migrating to new storage locations].
| + | * For more information about migrating your files, see [[Migrating Between Storage Locations]]. |
| | + | * 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.