This guide documents the classic version of the AWS Wickr administration console, released before March 13, 2025. For documentation on the new AWS Wickr administration console, see [ Administration Guide](https://docs.aws.amazon.com/wickr/latest/adminguide/what-is-wickr.html). # Configure data retention for AWS Wickr To configure data retention for your AWS Wickr network, you must deploy the data retention bot Docker image to a container on a host, such as a local computer or an instance in Amazon Elastic Compute Cloud (Amazon EC2). After the bot is deployed, you can configure it to store data locally or in an Amazon Simple Storage Service (Amazon S3) bucket. You can also configure the data retention bot to use other AWS services like AWS Secrets Manager (Secrets Manager), Amazon CloudWatch (CloudWatch), Amazon Simple Notification Service (Amazon SNS), and AWS Key Management Service (AWS KMS). The following topics describe how to configure and run the data retention bot for your Wickr network. **Topics** + [Prerequisites to configure data retention for AWS Wickr](#data-retention-prerequisites) + [Password for data retention bot in AWS Wickr](data-retention-password.md) + [Storage options for AWS Wickr network](data-retention-storage-options.md) + [Environment variables to configure data retention bot in AWS Wickr](data-retention-bot-env-variables.md) + [Secrets Manager values for AWS Wickr](data-retention-aws-secret-values.md) + [IAM policy to use data retention with AWS services](data-retention-aws-services.md) + [Start the data retention bot for your Wickr network](starting-data-retention-bot.md) + [Stop the data retention bot for your Wickr network](stopping-data-retention-bot.md) ## Prerequisites to configure data retention for AWS Wickr Before you get started, you must get the data retention bot name (labeled as **Username**) and initial password from the AWS Management Console for Wickr. You must specify both of these values the first time you start the data retention bot. You must also enable data retention in the console. For more information, see [View data retention details in AWS Wickr](view-data-retention-details.md). # Password for data retention bot in AWS Wickr The first time you start the data retention bot, you specify the initial password using one of the following options: + The `WICKRIO_BOT_PASSWORD` environment variable. The data retention bot environment variables are outlined in the [Environment variables to configure data retention bot in AWS Wickr](data-retention-bot-env-variables.md) section later in this guide. + The **password** value in Secrets Manager identified by the `AWS_SECRET_NAME` environment variable. The Secrets Manager values for the data retention bot are outlined in the [Secrets Manager values for AWS Wickr](data-retention-aws-secret-values.md) section later in this guide. + Enter the password when prompted by the data retention bot. You will need to run the data retention bot with interactive TTY access using the `-ti` option. A new password will be generated when you configure the data retention bot for the first time. If you need to re-install the data retention bot, you use the generated password. The initial password is not valid after the initial installation of the data retention bot. The new generated password will be displayed as shown in the following example. **Important** Save the password in a safe place. If you lose the password you will not be able to re-install the data retention bot. Don't share this password. It provides the ability to start data retention for your Wickr network. ``` ******************************************************************** **** GENERATED PASSWORD **** DO NOT LOSE THIS PASSWORD, YOU WILL NEED TO ENTER IT EVERY TIME **** TO START THE BOT "HuEXAMPLERAW4lGgEXAMPLEn" ******************************************************************** ``` # Storage options for AWS Wickr network After data retention is enabled and the data retention bot is configured for your Wickr network, it will capture all messages and files sent within your network. Messages are saved in files which are limited to a specific size or time limit that can be configured using an environment variable. For more information, see [Environment variables to configure data retention bot in AWS Wickr](data-retention-bot-env-variables.md). You can configure one of the following options for storing this data: + Store all captured messages and files locally. This is the default option. It's your responsibility to move local files to another system for long-term storage, and to make sure the host disk does not run out of memory or space. + Store all captured messages and files in an Amazon S3 bucket. The data retention bot will save all decrypted messages and files to the Amazon S3 bucket you specify. The captured messages and files are removed from the host machine after they are successfully saved to the bucket. + Store all captured messages and files encrypted in an Amazon S3 bucket. The data retention bot will re-encrypt all captured messages and files using a key that you supply and save them to the Amazon S3 bucket you specify. The captured messages and files are removed from the host machine after they are successfully re-encrypted and saved to the bucket. You will need software to decrypt the messages and files. For more information about creating an Amazon S3 bucket to use with your data retention bot, see [Creating a bucket](https://docs.aws.amazon.com/AmazonS3/latest/userguide/create-bucket-overview.html) in the *Amazon S3 User Guide* # Environment variables to configure data retention bot in AWS Wickr You can use the following environment variables to configure the data retention bot. You set these environment variables using the `-e` option when you run the data retention bot Docker image. For more information, see [Start the data retention bot for your Wickr network](starting-data-retention-bot.md). **Note** These environment variables are optional unless otherwise specified. Use the following environment variables to specify the data retention bot credentials: + `WICKRIO_BOT_NAME` — The name of the data retention bot. This variable is *required* when you run the data retention bot Docker image. + `WICKRIO_BOT_PASSWORD` — The initial password for the data retention bot. For more information, see [Prerequisites to configure data retention for AWS Wickr](configure-data-retention.md#data-retention-prerequisites). This variable is *required* if you don't plan to start the data retention bot with a password prompt or you don't plan to use Secrets Manager to store the data retention bot credentials. Use the following environment variables to configure the default data retention streaming capabilities: + `WICKRIO_COMP_MESGDEST` – The path name to the directory where messages will be streamed. The default value is `/tmp//compliance/messages`. + `WICKRIO_COMP_FILEDEST` – The path name to the directory where files will be streamed. The default value is `/tmp//compliance/attachments`. + `WICKRIO_COMP_BASENAME` – The base name for the received messages files. The default value is `receivedMessages`. + `WICKRIO_COMP_FILESIZE` – The maximum file size for a received messages file in kibibyte (KiB). A new file is started when the max size is reached. The default value is `1000000000`, as in 1024 GiB. + `WICKRIO_COMP_TIMEROTATE` – The amount of time, in minutes, for which the data retention bot will put received messages into a received messages file. A new file is started when the time limit is reached. You can only use the file size or time to limit the size of the received messages file. The default value is `0`, as in no limit. Use the following environment variable to define the default AWS Region to use. + `AWS_DEFAULT_REGION` – The default AWS Region to use for AWS services like Secrets Manager (not used for Amazon S3 or AWS KMS). The `us-east-1` Region is used by default if this environment variable is not defined. Use the following environment variables to specify the Secrets Manager secret to use when you opt to use Secrets Manager to store the data retention bot credentials and AWS service information. For more information about the values you can store in Secrets Manager see [Secrets Manager values for AWS Wickr](data-retention-aws-secret-values.md). + `AWS_SECRET_NAME` – The name of the Secrets Manager secret that contains the credentials and AWS service information needed by the data retention bot. + `AWS_SECRET_REGION` – The AWS Region that the AWS secret is located in. If you are using AWS secrets and this value is not defined the `AWS_DEFAULT_REGION` value will be used. **Note** You can store all of the following environment variables as values in Secrets Manager. If you opt to use Secrets Manager, and you store these values there, then you don't need to specify them as environment variables when you run the data retention bot Docker image. You only need to specify the `AWS_SECRET_NAME` environment variable described earlier in this guide. For more information, see [Secrets Manager values for AWS Wickr](data-retention-aws-secret-values.md). Use the following environment variables to specify the Amazon S3 bucket when you opt to store messages and files to a bucket. + `WICKRIO_S3_BUCKET_NAME` – The name of the Amazon S3 bucket where messages and files will be stored. + `WICKRIO_S3_REGION` – The AWS Region of the Amazon S3 bucket where messages and files will be stored. + `WICKRIO_S3_FOLDER_NAME` – The optional folder name in the Amazon S3 bucket where messages and files will be stored. This folder name will be preceded with the key for messages and files saved to the Amazon S3 bucket. Use the following environment variables to specify the AWS KMS details when you opt to use client side encryption to re-encrypt files when saving them to an Amazon S3 bucket. + `WICKRIO_KMS_MSTRKEY_ARN` – The Amazon Resource Name (ARN) of the AWS KMS master key used to re-encrypt the message files and files on the data retention bot before they are saved to the Amazon S3 bucket. + `WICKRIO_KMS_REGION` – The AWS Region where the AWS KMS master key is located. Use the following environment variable to specify the Amazon SNS details when you opt to send data retention events to an Amazon SNS topic. The events sent include startup, shutdown, as well as error conditions. + `WICKRIO_SNS_TOPIC_ARN` – The ARN of the Amazon SNS topic that you want data retention events sent to. Use the following environment variable to send data retention metrics to CloudWatch. If specified, the metrics will be generated every 60 seconds. + `WICKRIO_METRICS_TYPE` – Set the value of this environment variable to `cloudwatch` to send metrics to CloudWatch. # Secrets Manager values for AWS Wickr You can use Secrets Manager to store the data retention bot credentials and AWS service information. For more information about creating a Secrets Manager secret, see [Create an AWS Secrets Manager secret ](https://docs.aws.amazon.com/secretsmanager/latest/userguide/create_secret.html) in the *Secrets Manager User Guide*. The Secrets Manager secret can have the following values: + `password` – The data retention bot password. + `s3_bucket_name` – The name of the Amazon S3 bucket where messages and files will be stored. If not set, the default file streaming will be used. + `s3_region` – The AWS Region of the Amazon S3 bucket where messages and files will be stored. + `s3_folder_name` – The optional folder name in the Amazon S3 bucket where messages and files will be stored. This folder name will be preceded with the key for messages and files saved to the Amazon S3 bucket. + `kms_master_key_arn` – The ARN of the AWS KMS master key used to re-encrypt the message files and files on the data retention bot before they are saved to the Amazon S3 bucket. + `kms_region` – The AWS Region where the AWS KMS master key is located. + `sns_topic_arn` – The ARN of the Amazon SNS topic that you want data retention events sent to. # IAM policy to use data retention with AWS services If you plan to use other AWS services with the Wickr data retention bot, you must ensure the host has the appropriate AWS Identity and Access Management (IAM) role and policy to access them. You can configure the data retention bot to use Secrets Manager, Amazon S3, CloudWatch, Amazon SNS, and AWS KMS. The following IAM policy allows access to specific actions for these services. ------ #### [ JSON ] **** ``` { "Version":"2012-10-17", "Statement": [ { "Sid": "VisualEditor0", "Effect": "Allow", "Action": [ "s3:PutObject", "secretsmanager:GetSecretValue", "sns:Publish", "cloudwatch:PutMetricData", "kms:GenerateDataKey" ], "Resource": "*" } ] } ``` ------ You can create an IAM policy that is more strict by identifying the specific objects for each service that you want to allow the containers on your host to access. Remove the actions for the AWS services that you do not intend to use. For example, if you intent to use only an Amazon S3 bucket, then use the following policy, which removes the `secretsmanager:GetSecretValue`, `sns:Publish`, `kms:GenerateDataKey`, and `cloudwatch:PutMetricData` actions. ------ #### [ JSON ] **** ``` { "Version":"2012-10-17", "Statement": [ { "Sid": "VisualEditor0", "Effect": "Allow", "Action": "s3:PutObject", "Resource": "*" } ] } ``` ------ If you are using an Amazon Elastic Compute Cloud (Amazon EC2) instance to host your data retention bot, create an IAM role using the Amazon EC2 common case and assign a policy using the policy definition from above. # Start the data retention bot for your Wickr network Before you run the data retention bot, you should determine how you want to configure it. If you plan to run the bot on a host that: + Will not have access to AWS services, then your options are limited. In that case you will use the default message streaming options. You should decide whether you want to limit the size of the captured message files to a specific size or time interval. For more information, see [Environment variables to configure data retention bot in AWS Wickr](data-retention-bot-env-variables.md). + Will have access to AWS services, then you should create a Secrets Manager secret to store the bot credentials, and AWS service configuration details. After the AWS services are configured, you can proceed to start the data retention bot Docker image. For more information about the details you can store in a Secrets Manager secret, see [Secrets Manager values for AWS Wickr](data-retention-aws-secret-values.md) The following sections show example commands to run the data retention bot Docker image. In each of the example commands, replace the following example values with your own: + `compliance_1234567890_bot` with the name of your data retention bot. + `password` with the password for your data retention bot. + `wickr/data/retention/bot` with the name of your Secrets Manager secret to use with your data retention bot. + `bucket-name` with the name of the Amazon S3 bucket where messages and files will be stored. + `folder-name` with the folder name in the Amazon S3 bucket where messages and files will be stored. + `us-east-1` with the AWS Region of the resource you're specifying. For example, the Region of the AWS KMS master key or the Region of the Amazon S3 bucket. + `arn:aws:kms:us-east-1:111122223333:key/12345678-1234-abcde-a617-abababababab` with the Amazon Resource Name (ARN) of your AWS KMS master key to use to re-encrypt message files and files. # Start the bot with password environment variable (no AWS service) The following Docker command starts the data retention bot. The password is specified using the `WICKRIO_BOT_PASSWORD` environment variable. The bot starts using the default file streaming, and using the default values defined in the [Environment variables to configure data retention bot in AWS Wickr](data-retention-bot-env-variables.md) section of this guide. ``` docker run -v /opt/compliance_1234567890_bot:/tmp/compliance_1234567890_bot \ -d --restart on-failure:5 --name="compliance_1234567890_bot" -ti \ -e WICKRIO_BOT_NAME='compliance_1234567890_bot' \ -e WICKRIO_BOT_PASSWORD='password' \ wickr/bot-compliance-cloud:latest ``` # Start the bot with password prompt (no AWS service) The following Docker command starts the data retention bot. Password is entered when prompted by the data retention bot. It will start using the default file streaming using the default values defined in the [Environment variables to configure data retention bot in AWS Wickr](data-retention-bot-env-variables.md) section of this guide. ``` docker run -v /opt/compliance_1234567890_bot:/tmp/compliance_1234567890_bot \ -d --restart on-failure:5 --name="compliance_1234567890_bot" -ti \ -e WICKRIO_BOT_NAME='compliance_1234567890_bot' \ wickr/bot-compliance-cloud:latest docker attach compliance_1234567890_bot . . . Enter the password:************ Re-enter the password:************ ``` Run the bot using the `-ti` option to receive the password prompt. You should also run the `docker attach ` command immediately after starting the docker image so that you get the password prompt. You should run both of these commands in a script. If you attach to the docker image and don’t see the prompt, press **Enter** and you will see the prompt. # Start the bot with 15 minute message file rotation (no AWS service) The following Docker command starts the data retention bot using environment variables. It also configures it to rotate the received messages files to 15 minutes. ``` docker run -v /opt/compliance_1234567890_bot:/tmp/compliance_1234567890_bot --network=host \ -d --restart on-failure:5 --name="compliance_1234567890_bot" -ti \ -e WICKRIO_BOT_NAME='compliance_1234567890_bot' \ -e WICKRIO_BOT_PASSWORD='password' \ -e WICKRIO_COMP_TIMEROTATE=15 \ wickr/bot-compliance-cloud:latest ``` # Start the bot and specify the initial password with Secrets Manager You can use the Secrets Manager to identify the data retention bot’s password. When you start the data retention bot, you will need to set an environment variable that specifies the Secrets Manager where this information is stored. ``` docker run -v /opt/compliance_1234567890_bot:/tmp/compliance_1234567890_bot --network=host \ -d --restart on-failure:5 --name="compliance_1234567890_bot" -ti \ -e WICKRIO_BOT_NAME='compliance_1234567890_bot' \ -e AWS_SECRET_NAME='wickrpro/alpha/new-3-bot' \ wickr/bot-compliance-cloud:latest ``` The `wickrpro/compliance/compliance_1234567890_bot` secret has the following secret value in it, shown as plaintext. ``` { "password":"password" } ``` # Start the bot and configure Amazon S3 with Secrets Manager You can use the Secrets Manager to host the credentials, and the Amazon S3 bucket information. When you start the data retention bot, you will need to set an environment variable that specifies the Secrets Manager where this information is stored. ``` docker run -v /opt/compliance_1234567890_bot:/tmp/compliance_1234567890_bot --network=host \ -d --restart on-failure:5 --name="compliance_1234567890_bot" -ti \ -e WICKRIO_BOT_NAME='compliance_1234567890_bot' \ -e AWS_SECRET_NAME='wickrpro/alpha/compliance_1234567890_bot' \ wickr/bot-compliance-cloud:latest ``` The `wickrpro/compliance/compliance_1234567890_bot` secret has the following secret value in it, shown as plaintext. ``` { "password":"password", "s3_bucket_name":"bucket-name", "s3_region":"us-east-1", "s3_folder_name":"folder-name" } ``` Messages and files received by the bot will be put in the `bot-compliance` bucket in the folder named `network1234567890`. # Start the bot and configure Amazon S3 and AWS KMS with Secrets Manager You can use the Secrets Manager to host the credentials, the Amazon S3 bucket, and AWS KMS master key information. When you start the data retention bot, you will need to set an environment variable that specifies the Secrets Manager where this information is stored. ``` docker run -v /opt/compliance_1234567890_bot:/tmp/compliance_1234567890_bot --network=host \ -d --restart on-failure:5 --name="compliance_1234567890_bot" -ti \ -e WICKRIO_BOT_NAME='compliance_1234567890_bot' \ -e AWS_SECRET_NAME='wickrpro/alpha/compliance_1234567890_bot' \ wickr/bot-compliance-cloud:latest ``` The `wickrpro/compliance/compliance_1234567890_bot` secret has the following secret value in it, shown as plaintext. ``` { "password":"password", "s3_bucket_name":"bucket-name", "s3_region":"us-east-1", "s3_folder_name":"folder-name", "kms_master_key_arn":"arn:aws:kms:us-east-1:111122223333:key/12345678-1234-abcde-a617-abababababab", "kms_region":"us-east-1" } ``` Messages and files received by the bot will be encrypted using the KMS key identified by the ARN value, then put in the “bot-compliance'” bucket in the folder named “network1234567890”. Make sure you have the appropriate IAM policy setup. # Start the bot and configure Amazon S3 using environment variables If you don't want to use Secrets Manager to host the data retention bot credentials, you can start the data retention bot Docker image with the following environment variables. You must identify the name of the data retention bot using the `WICKRIO_BOT_NAME` environment variable. ``` docker run -v /opt/compliance_1234567890_bot:/tmp/compliance_1234567890_bot --network=host \ -d --restart on-failure:5 --name="compliance_1234567890_bot" -ti \ -e WICKRIO_BOT_NAME='compliance_1234567890_bot' \ -e WICKRIO_BOT_PASSWORD='password' \ -e WICKRIO_S3_BUCKET_NAME='bot-compliance' \ -e WICKRIO_S3_FOLDER_NAME='network1234567890' \ -e WICKRIO_S3_REGION='us-east-1' \ wickr/bot-compliance-cloud:latest ``` You can use environment values to identify the data retention bot’s credentials, information about Amazon S3 buckets, and configuration information for the default file streaming. # Stop the data retention bot for your Wickr network The software running on the data retention bot will capture `SIGTERM` signals and gracefully shutdown. Use the `docker stop ` command, as shown in the following example, to issue the `SIGTERM` command to the data retention bot Docker image. ``` docker stop compliance_1234567890_bot ```