You are here

Properties reference

The S3 Connector provides a number of properties on installation and for customizing your configuration.
The sections in this page describe what's changed in the properties configuration:

New properties

Here is a list of properties that have been added in S3 Connector 3.1.

connector.s3.objectNamePrefix
Blank by default
The value of this property will be appended (prefixed) to the AWS S3 URL for each uploaded file.
If used, it should typically represent a directory in S3, and be terminated by a "/" (slash) character (although this is not mandatory). For example:
connector.s3.objectNamePrefix=some/bucket/directory/
When no value is set (i.e. the default) files are uploaded directly into the root of the S3 bucket. This is a more generic replacement of the dir.s3.contentstore and s3.useContentRootInPath configuration properties.
Note: The value of this property is not saved in the database with the contentUrl. It's appended dynamically when S3 content is accessed. Therefore, the value of this property shouldn't be changed without first moving/renaming the existing content to the new location.
connector.s3.objectNameSuffix
Blank by default
Previous versions of the S3 Connector (v2.0.0 - 3.0.0) appended the ".bin" extension to the contentUrl. Although not ideal, we keep this scheme for the sake of consistency. All S3 file URLs will use the ".bin" extension, as that's the hard-coded behavior.
The value of this property will be appended as a suffix to the AWS S3 URL for each uploaded file.
If used, it should typically represent a file extension, and have a pattern starting with a "." (dot). For example:
connector.s3.objectNamePrefix=.something
Note: The value of this property is not saved in the database with the contentUrl. It's appended dynamically when S3 content is accessed. Therefore, the value of this property shouldn't be changed without renaming the existing content with the new suffix pattern.
connector.s3.deleted.objectNamePrefix
Default value: ${dir.s3.contentstore.deleted}/
This is a similar property to connector.s3.objectNamePrefix, but it affects the DeletedContentStore:
The DeletedContentStore holds the files removed/deleted from Alfresco (including from the Alfresco Trash bin).
Unlike the property for the regular content store (blank by default), it defaults to the dir.s3.contentstore.deleted property, which is equivalent to dir.contentstore.deleted, used by the DeletedContentStore prior to v3.1.0.
Note: It is recommended that the value is never be left blank, as that would result in the deleted files always residing in the same bucket directory as the actual active Alfresco Content Services content. This could lead to complications when configuring the AWS S3 cleanup job for removed Alfresco Content Services content (with the worst case scenario being it would delete content that's not yet removed from Alfresco Content Services).
connector.s3.deleted.objectNameSuffix
Blank by default
This property is similar to connector.s3.objectNameSuffix, but it only affects the DeletedContentStore.
connector.s3.storeProtocol
Default value: s3v2
Allows custom protocol values in the Alfresco Content Services content URL (the file references stored in the database). This property should help with custom configurations of Alfresco Content Services with multiple instances of the S3 content stores.
Note: The old "s3" store protocol is no longer used for new content, nor can it be configured through this new configuration property, as that's a forbidden value. However, old content that has already been created with the "s3" store protocol is still readable by the S3 Connector.
filecontentstore.subsystem.name
Default value: S3OnPrem
Defines the content store subsystem. Although the default value is S3OnPrem, this can be changed to any content store subsystem name that's available in the system.

See S3 Connector content store subsystems for more details.

connector.s3.tagName
Blank by default
Defines a tag to apply to the content when it's written into the S3 bucket. If used, it also requires the tagValue property to be populated. This allows you to define your own custom lifecycle policies based on tags.
Note: Use the AWS documentation Object key and metadata for naming guidelines, as the properties must respect the same restrictions as if they were added via the AWS Management Console.
connector.s3.tagValue
Blank by default
Defines a tag to apply to the content when it's written into the S3 bucket. If used, it also requires the tagName property to be populated. This allows you to define your own custom lifecycle policies based on tags.

back to top

New properties that supersede older properties

To help align the configuration properties across the Alfresco connectors (in particular between the S3 Connector and the Azure Connector), a number of new properties have been introduced, with the final purpose of replacing their older equivalents in time.

New property Defaults to old property
connector.s3.maxErrorRetries ${s3.maxErrorRetries}
connector.s3.httpRequestTimeout ${s3.httpRequestTimeout}
connector.s3.abortIncompleteMultipartUploadDays ${s3.abortIncompleteMultipartUploadDays}
connector.s3.bucketName ${s3.bucketName}
connector.s3.bucketRegion ${s3.bucketLocation}
connector.s3.endpoint ${s3.endpoint}
connector.s3.accessKey ${s3.accessKey}
connector.s3.secretKey ${s3.secretKey}
connector.s3.encryption ${s3.encryption}
connector.s3.awsKmsKeyId ${s3.awsKmsKeyId}
Note: The new configuration properties default to the equivalent older properties (i.e. properties without the "connector.*" prefix). This ensures that upgrades of the S3 Connector will not require configuration updates. However, it is recommended that you use the newer properties.

Until now, the S3 Connector would override and use dir.contentstore and dir.contentstore.deleted properties defined in the repository.properties file in Alfresco Content Services (for fileContentStore and deletedContentStore).

Starting from version 3.1, the S3 Connector provides out-of-the-box content store subsystems. The subsystem approach allows a more flexible use of the S3 content store, even in conjunction with existing content stores.

Important: In this case, we should not override the properties mentioned in the deprecated and superseded sections with S3 specific values. Instead, new properties have been introduced to be used only by the S3 Connector:
  • dir.s3.contentstore - defaults to contentstore
  • dir.s3.contentstore.deleted - defaults to contentstore.deleted

dir.s3.contentstore
Directory name used within the S3 bucket for the contentstore. The default is contentstore.
dir.s3.contentstore.deleted
Directory name used within the S3 bucket for the deleted contentstore. The default is contentstore.deleted.
connector.s3.bucketName
The bucket name must be unique among all AWS users globally. If the bucket does not already exist, it will be created, but the name must not have already been taken by another user. If the bucket has an error, it will be reported in the alfresco.log file.
connector.s3.bucketRegion
The location where the new S3 bucket should be created if it doesn't exist.
For a list of available AWS Regions, see Regions and Endpoints in the AWS General Reference. The default region is US East (N. Virginia) - i.e. us-east-1.
connector.s3.endpoint
This is blank by default, but it can be used to add a custom endpoint, for example connector.s3.endpoint=s3.us-gov-west-1.amazonaws.com.
connector.s3.maxErrorRetries
The maximum number of attempts to retry reads or writes to the S3 bucket in case of failed transfers. The default is 3.
This configuration uses throttling retries. See Retry Throttling for more details.

connector.s3.abortIncompleteMultipartUploadDays
The minimum number of days that AWS S3 should keep the incomplete multipart upload parts before marking them for deletion. If the value is 0 then the abort is disabled. The default is 1.

If the bucket (identified by the value of connector.s3.bucketName) doesn't already exist, then we create the bucket and a global lifecycle rule to enforce the abort and deletion of incomplete uploads after the specified number of days. When an object reaches the end of its lifetime, Amazon S3 queues it for removal and removes it asynchronously.

Note: There may be a delay between the expiration date and the date on which AWS S3 removes an object.
connector.s3.encryption
Encryption to be applied for content stored in AWS S3. Two options are supported for managing encryption keys: AES256 and KMS. The default value on installation is AES256.

connector.s3.awsKmsKeyId
Indicates the key alias or ARN to be used for KMS encryption.

For more details see create a key using KMS key material origin or by importing key material in AWS Key Management Service.

If no value is provided, the default master key attached to your account is used. See Protecting Data Using Server-Side Encryption with AWS KMS-Managed Keys (SSE-KMS).

connector.s3.accessKey
Required to identify the AWS account and can be obtained from the AWS Management Console. See AWS Credentials for access details. This property is not required if you plan to use IAM roles.
connector.s3.secretKey
Required to identify the AWS account and can be obtained from the AWS Management Console. See AWS Credentials for access details. This property is not required if you plan to use IAM roles.

back to top

Properties deprecated in S3 Connector 3.1

The following properties are deprecated in S3 Connector 3.1, and should no longer be used as they'll be removed in a future release.
s3.useContentRootInPath
The default is false. When set to true, Alfresco Content Services won't start, and you'll see an error:
The V1 storage protocol s3:// has been deprecated since version 2.0 of this connector 
and has been removed. This version no longer supports  s3.useContentRootInPath
parameter being set to true. If you need to partition the objects in your bucket, we 
recommend either using tags or the new connector.s3.objectNamePrefix option.

Check Replicating s3.useContentRootInPath behavior for details of how to replicate the old behavior of the s3.useContentRootInPath option through new configuration properties.

s3.useTenantDomainInPath
Defines whether the tenant name is used in the S3 path. The default is false. When set to either true or false, you'll see a warning specifying that multi-tenancy is no longer supported:
Multi-tenancy is no longer supported
In spite of the warning, the behavior of the S3 Connector hasn't changed in relation to this property. However, only content store beans of type org.alfresco.integrations.connector.TenantS3ContentStore actually contain logic that can interpret this property. (In the S3 Connector default Spring configuration, there's currently only one such bean: tenantS3ContentStore).
s3.autoLowerCaseBucketName
The default is false. When set to either true or false, you'll see a warning:
The property s3.autoLowerCaseBucketName is no longer supported
In spite of the warning, the S3 Connector behavior hasn't changed yet.
s3.flatRoot
Defines whether all content items should be stored in the same single directory in the bucket, otherwise the standard date-based hierarchy is used. The default is true. When set to false, you'll see a warning:
The property flatRoot is no longer supported, is highly discouraged, and will be 
removed with the next release.
In spite of the warning, the configuration is still evaluated and followed (i.e. no behavior changes yet).

back to top

Sending feedback to the Alfresco documentation team

You don't appear to have JavaScript enabled in your browser. With JavaScript enabled, you can provide feedback to us using our simple form. Here are some instructions on how to enable JavaScript in your web browser.