Configure regions and S3 connections

Connection settings tell S3Client which service to contact and how to address and sign its requests. You can set an endpoint and signing region for one bucket without changing the connections used by other buckets in the account.

A region combines a local name, a signing region, and an S3 endpoint. The account has a region list and a Default region for requests without a more specific region. Protocol and port are shared across the account; each region has its own signing and addressing settings.

Have the hostname, signing region, port, and supported options ready for your service. The provider preset supplies these values when the account is created; you can change them later. Credentials are configured separately under Credentials.

Open the account settings#

1. In the main window, choose File > Accounts….
2. Select the account and click Edit….
3. In Account, open Regions.
4. Select a region and click Edit, or double-click it. To add one, click Add.

The dialog is called Edit region, including when adding a region. Connection settings are on General, and control routes are on S3 Control. Changes are saved to the account only after you click OK in this dialog and then OK in Account.

Configure a region#

Name, Region, and Endpoint are required. The list rejects duplicate names, region codes, or endpoints, ignoring case. This region already exists !, This region name already exists !, or This endpoint already exists ! identifies the conflicting field.

An account supports up to 100 regions and must retain a default region. Names, region codes, and copy domains are limited to 4,096 characters; an endpoint is limited to 253 characters in its normalized form. Configurations exceeding these limits cannot be saved.

Endpoint also accepts IPv4 or IPv6 addresses, such as 192.0.2.10 or [2001:db8::10]. An IP endpoint requires Path-style; otherwise, saving is rejected with IP literals require path-style addressing.

S3-compatible storage starts with local name Default region, code us-east-1, and endpoint localhost. Replace the endpoint and code as required by your service. A manually added region starts with AWS Signature v2, Hosted-style, Account Regional bucket namespace available checked, and S3 Control routes disabled. Explicitly choose suitable values; they are not inferred from the hostname.

Choose addressing#

Choose an addressing mode accepted by the service. The service must also support path addressing if you select fallback for dotted bucket names.

Port, TLS, and default region#

1. Click OK in Edit region.
2. Open the Account tab.
3. Select Default region from the configured regions.
4. Set Port, from 1 to 65535.
5. Check Connect using SSL/TLS for HTTPS, or uncheck it for HTTP if required by the service.
6. Use Test connection, then OK to save.

Both built-in presets use HTTPS on port 443. Changing TLS does not automatically change the port. HTTP does not encrypt traffic.

The Server-side copy domain on the Account tab is used when the region does not supply one. Without an explicit domain, the domain is specific to this S3Client account. Before assigning the same domain to multiple accounts, check that they really share a server-side bucket namespace: an incorrect declaration can cause a copy to read a different object with the same name. Direct copies between accounts also require Allow direct copies with other accounts on both accounts. See Copy between S3 accounts.

Delete or restore regions#

Before changing, deleting, or restoring a region, check the bucket connections that use it. Changing the code, endpoint, signature version, addressing style, port, or TLS can invalidate a saved connection. The saved bucket connection no longer matches the account settings. Configure the bucket connection again. means you need to reopen Bucket connection…, check the fields, and click Save. Renaming only the account or a region’s local name does not change its network connection.

Also check Assignments under Capabilities > Encryption policies, Storage classes, Lifecycle, and Static website hosting. These assignments match Region location or Endpoint, rather than the local name. Editing a region does not update their criteria: an assignment that no longer matches may allow another assignment, or the default policy, to apply. Update the criteria before saving the account. See Configure account capabilities.

In Regions, select a region, click Remove, and confirm with Yes. This removes local settings without deleting a region or bucket on the service. Check Default region afterward: deleting or renaming the default region may require selecting it again.

Restore Defaults replaces the editor’s entire region list with the associated preset’s values when available. If the custom preset is no longer available, S3Client uses the account’s current regions as its baseline. This does not restore credentials or all capabilities. Check the list and default region before clicking OK in Account; Cancel discards the changes.

Configure a bucket connection#

A local connection associates a bucket with a signing region and an endpoint allowed by the account. It applies to that bucket and all its favorites within the account. It does not move the bucket or change its region on the service.

1. In an S3 browser pane outside Preview mode, display the bucket or one of its folders using the relevant account. Wait for any opening or refresh request to finish.
2. Click the account icon button beside Address, whose tooltip is Account and connection…, then choose Bucket connection….
3. In Bucket connection, select Signing region, or enter the required code. Selecting a listed region also fills in its endpoint.
4. Check Endpoint. This host must already appear in the account’s regions. If necessary, click Account settings…, configure it under Regions, and save the account.
5. Click Save to save the connection, or Cancel to discard it.
6. Open the S3 location again to check access.

If the signing code is known to the account, its signing and addressing settings are used; otherwise, the default region’s settings are used with the code you entered. Port and TLS remain those of the account. Configure this endpoint in the account settings before using it for the bucket. asks you to add the host to the account; Enter a valid signing region for the bucket. asks for a valid code.

Reload connection discards entries and reloads the connection in this order: a region hint from the location or favorite, otherwise the saved connection, otherwise the default region. Returning from Account settings… also reloads the fields, even if you canceled the account editor. After configuration changes or a concurrent edit, check those values before saving again. You can also open Bucket connection… from the editor for an S3 favorite.

A service response can specify a different region or a permanent redirect. S3Client can then update and save the bucket connection, even if you configured it manually. A temporary redirect does not change the saved connection. The target must be allowed by the account endpoints or current host; the port is preserved, and an HTTPS connection cannot switch to HTTP.

Configure S3 Control and the account ID#

Tag operations using S3 Control resource tagging need a control route separate from the S3 data endpoint. In Edit region, the S3 Control tab contains two independent groups: General purpose buckets and Directory buckets. Having these routes in an account does not mean every feature can use every bucket type.

Before reading or editing tags through S3 Control, enter the twelve-digit service account number under Account > Account > Account ID and choose S3 Control resource tagging under Capabilities > Bucket tags > Tag editing API. This number is not an access key.

1. In Account > Regions, click Edit for the relevant region.
2. Open the S3 Control tab.
3. Under General purpose buckets or Directory buckets, check Enable control route.
4. Fill in the fields below as required by the service.
5. Click OK, then OK in Account to save.

Enter the host template in lowercase, without a trailing dot, protocol, port, or path. Its length after substitution is limited to 253 characters. {accountId} is the only supported variable and is accepted only for general purpose buckets; {region} and all other substitutions are rejected. If the hostname supplied by the service contains a region code, enter the actual value rather than {region}. If a route is invalid when you click OK, S3Client displays Invalid S3 Control routing and selects the S3 Control tab. Correct the reported problem, then click OK again.

Uncheck Enable control route to remove that route from the saved settings. The group’s other fields become unavailable. S3Client does not invent a control endpoint when one is missing for a custom endpoint.

Without Account ID, you can save the S3 Control policy, but reading and editing bucket tags remain unavailable. A missing or invalid route also prevents the relevant control operations. Test connection checks an S3 read, not the S3 Control route or permissions to write tags. After saving, check those features in the relevant bucket’s properties.

S3 Control tagging also requires a non-external bucket, a bucket region configured in the account, and an ARN matching the bucket name, type, and partition. For a directory bucket, the ARN must also match the region and owner account. A missing ARN is reconstructed only when Capabilities > General > Standard S3 resource identifiers (ARNs) is enabled. S3ControlConfigurationIncomplete means a prerequisite is missing or inconsistent; read its details before correcting the ID, route, or ARN. Control requests always use signature v4 and do not follow HTTP redirects.

Check the result#

A valid connection also requires a complete credential source and an account name. Test connection uses the editor’s settings without saving them. Review its scope and errors, then save with OK. Proxy and network errors are handled in network options.