Step 1: Configure permissions and Started Task Control (STC)Step 2: Create Amazon S3 buckets Step 3: Create an AWS KMS customer managed key for encryption Step 4: Create an AWS Secrets Manager secret for the mainframe credentials Step 5: Create an IAM policy Step 6: Create an IAM user with long-term access credentials Step 7: Create an IAM role for the agent to assume Step 8: Agent configuration

Configure a File Transfer agent

Once you have installed a file transfer agent, follow these steps to configure the agent. If you need to install a new agent, follow instructions on the Install a File Transfer agent page.

Topics

Step 1: Configure permissions and Started Task Control (STC)
Step 2: Create Amazon S3 buckets
Step 3: Create an AWS KMS customer managed key for encryption
Step 4: Create an AWS Secrets Manager secret for the mainframe credentials
Step 5: Create an IAM policy
Step 6: Create an IAM user with long-term access credentials
Step 7: Create an IAM role for the agent to assume
Step 8: Agent configuration

Step 1: Configure permissions and Started Task Control (STC)

Update and submit one of SYS2.AWS.M2.SAMPLIB(SEC#RACF) (for setting up RACF permissions) or SYS2.AWS.M2.SAMPLIB(SEC#TSS) (for setting up TSS permissions) in accordance with their instructions. These members were created by the previous CPY#PDS step.

Note
SYS2.AWS.M2 is the high-level qualifier (HLQ) that was chosen during the install.
Update the PWD export in the SYS2.AWS.M2.SAMPLIB(M2AGENT) STC JCL, if the default File Transfer agent directory path(/usr/lpp/aws/m2-agent) was changed.
Update and copy the SYS2.AWS.M2.SAMPLIB(M2AGENT) JCL to SYS1.PROCLIB.
Add SYS2.AWS.M2.LOADLIB to the APF list using the following command:
```
SETPROG APF ADD DSNAME(SYS2.AWS.M2.LOADLIB) SMS
```
Set the agent’s logs and diag folders' group and owner to the agent user/group (M2USER/M2GROUP). Use the following command:
```
chown -R M2USER:M2GROUP $AGENT_DIR/current-version/logs
chown -R M2USER:M2GROUP $AGENT_DIR/current-version/diag
```

Step 2: Create Amazon S3 buckets

AWS Mainframe Modernization File Transfer requires an intermediate Amazon S3 bucket as a work area. We recommend creating a bucket specifically for this.

Optionally, create a new target Amazon S3 bucket for the transferred data sets. Otherwise you can also use your existing Amazon S3 bucket. For more information on creating Amazon S3 buckets, see Creating a bucket.

Step 3: Create an AWS KMS customer managed key for encryption

To create a customer managed key in AWS KMS

Open the AWS KMS console at https://console.aws.amazon.com/kms.
Choose Customer managed keys in left navigation pane.
Choose Create key.
Under Configure key, choose Key type as Symmetric, and Key usage as encrypt and decrypt. Use other default configurations.
In Add labels, add Alias and description for your key.
Choose Next.
Under Define key administrative permissions, choose at least one IAM user and role who administers this key.
Choose Next.
On the Review page, add the following syntax to the Key policy. This allows the AWS Mainframe Modernization service to read and use these keys for encryption/decryption.

Important
Add the statement to the existing statements. Don't replace what's already in the policy.
```
{
    "Sid" : "Enable AWS M2 File Transfer Permissions",
    "Effect" : "Allow",
    "Principal" : {
        "Service" : "m2.amazonaws.com"
    },
    "Action" : [
        "kms:Encrypt",
        "kms:Decrypt"
    ],
   "Resource" : "*"
},
```

Save the ARN for the customer managed key once it is created. It will be used in the policy later.

Step 4: Create an AWS Secrets Manager secret for the mainframe credentials

Mainframe credentials are required to access the data sets to be transferred and these must be stored as an AWS Secrets Manager secret.

To create an AWS Secrets Manager secret

Open Secrets manager console at https://console.aws.amazon.com/secretsmanager.
In Choose Secret type, choose Other type of secret.
Use the key value userId for the mainframe userId that has access to the data sets.
Use the key value password for the password field.
For Encryption Key, choose the AWS customer managed key created earlier.
Choose Next.
On the Configure secret page, provide a name and description.

On the same page, edit the Resource permissions, and use the following resource policy so the AWS Mainframe Modernization service can access it.


{
  "Version" : "2012-10-17",
  "Statement" : [ {
    "Effect" : "Allow",
    "Principal" : {
        "Service" : "m2.amazonaws.com"
    },
    "Action" : [ "secretsmanager:GetSecretValue", 
                 "secretsmanager:DescribeSecret" ],
    "Resource" : "*"
  } ]
}

Choose Save to save the updated permissions before choosing Next.
Skip throughConfigure rotations page, and choose Next.
On the Review page, check all configurations and choose Store to save the secret.

Important

The userId and password secret keys are case-sensitive and must be entered as shown.

Step 5: Create an IAM policy

To create a new policy with the permissions required for the agent

Switch from the Visual editor to the JSON editor and replace the contents with the following template:


{
"Version": "2012-10-17",
    "Statement": [
        {
         "Sid": "FileTransferAgentSQSReceive",
            "Effect": "Allow",
            "Action": [
                "sqs:DeleteMessage",
                "sqs:ReceiveMessage"
            ],
            "Resource": "arn:aws:sqs:*:111122223333:m2-*-request-queue.fifo"
        },
        {
         "Sid": "FileTransferAgentSQSSend",
            "Effect": "Allow",
            "Action": "sqs:SendMessage",
            "Resource": "arn:aws:sqs:*:111122223333:m2-*-response-queue.fifo"
        },
        {
         "Sid": "FileTransferWorkingS3",
            "Effect": "Allow",
            "Action": "s3:PutObject",
            "Resource": "<file-transfer-endpoint-intermediate-bucket-arn>/*"
        },
        {
         "Sid": "FileTransferAgentKMSDecrypt",
            "Effect": "Allow",
            "Action": "kms:Decrypt",
            "Resource": "<kms-key-arn>"
        }
    ]
}

Replace the 111122223333 in the request-queue and response-queue ARN’s with your account.

Note
These are wildcard ARN’s that match the two Amazon SQS queues created during the data transfer endpoint initialization. After creating a File Transfer endpoint, optionally replace these ARN’s with the actual values from Amazon SQS.
Replace file-transfer-endpoint-intermediate-bucket-arn with the ARN of the transfer bucket created earlier. Leave the “/*” wildcard at the end.
Replace kms-key-arn with the ARN of the AWS KMS key created earlier.

Step 6: Create an IAM user with long-term access credentials

Create an IAM user that allows the mainframe agent to connect to your AWS account. The agent will connect with this user and then assume a role you define with permissions to use Amazon SQS response and request queues and to save datasets to Amazon S3 buckets.

To create this IAM user

Navigate to AWS IAM console at https://console.aws.amazon.com/iam.
In the Permissions options, choose the Attach policies directly option but do not attach any permissions policies. These permissions will be managed by a role that will be attached.
Once the user is created, choose the user and open Security credentials tab.
In Create access key, choose Other when prompted for Use case.
Copy and securely save the generated Access key and Secret access key. These will be used later.

For more information on creating IAM access key, see Managing access keys for IAM users.

Important

Save the Access key and Secret access key displayed on the last page of the access key creation wizard, before choosing Done. These keys are used to configure the mainframe agent.

Note

Save the IAM user ARN used to set up a trust relationship with an IAM role.

Step 7: Create an IAM role for the agent to assume

To create a new IAM role for the agent

Choose Roles in the IAM console at https://console.aws.amazon.com/iam.
Choose Create role.
On the Select trusted entity page, choose Custom trust policy for the Trusted entity type.

Replace the Custom trust policy with the following and replace <iam-user-arn> with the ARN of the user created earlier.


{
    "Version": "2012-10-17",
    "Statement": [ {
         "Sid": "FileTransferAgent",
         "Effect": "Allow",
         "Principal": {
            "AWS": "<IAM-User-arn>"
         },
         "Action": "sts:AssumeRole"
    } ]
}

Choose Next.
In Add Permissions, filter for the Policy name you created earlier and choose it.
Choose Next.
Name the role, and choose Create Role.

Note

Save the role name, which you will use later to configure the mainframe agent.

Step 8: Agent configuration

To configure the File Transfer agent

Navigate to $AGENT_DIR/current-version/config.
Edit the agent’s configuration file appication.properties to add an environments configuration using the following command:
```
oedit $AGENT_DIR/current-version/config/application.properties
```
For example:
```
agent.environments[0].account-id=<AWS_ACCOUNT_ID>
agent.environments[0].agent-role-name=<AWS_IAM_ROLE_NAME>
agent.environments[0].access-key-id=<AWS_IAM_ROLE_ACCESS_KEY>
agent.environments[0].secret-access-id=<AWS_IAM_ROLE_SECRET_KEY>
agent.environments[0].bucket-name=<AWS_S3_BUCKET_NAME>
agent.environments[0].environment-name=<AWS_REGION>
agent.environments[0].region=<AWS_REGION>
zos.complex-name=<File_Transfer_Endpoint_Name>
```
Where:
- AWS_ACCOUNT_ID is the ID of the AWS account.
- AWS_IAM_ROLE_NAME is the name of the IAM role created in the Step 7: Create an IAM role for the agent to assume.
- AWS_IAM_ROLE_ACCESS_KEY is the access key of the IAM user created in Step 6: Create an IAM user with long-term access credentials.
- AWS_IAM_ROLE_SECRET_KEY is the access secret key for the IAM user created in Step 6: Create an IAM user with long-term access credentials.
- AWS_S3_BUCKET_NAME is the name of the transfer bucket created with the data transfer endpoint.
- AWS_REGION is the region in which you configure the File Transfer agent.
  
  Note
  You can have the File Transfer agent transfer to multiple regions and accounts in AWS by defining multiple environments.
- (Optional). zos.complex-name is the complex name you created when creating a File Transfer endpoint.
  
  Note
  This field is necessary only if you want to customize the complex name (which defaults to your sysplex name) that is the same as you defined when creating your File Transfer endpoint. For more information, see Create data transfer endpoints for File Transfer.
Important
There can be several such sections, as long as the index in brackets — [0]— is incremented for each.

You must restart the agent for changes to take effect.

Requirements

When a parameter is added or removed, the agent has to be stopped and started. Start the File transfer agent using the following command in the CLI:
```
/S M2AGENT
```
To stop the M2 agent, use the following command in CLI:
```
/P M2AGENT
```

You can have the File Transfer agent transfer to multiple regions and accounts in AWS by defining multiple environments.

Note

Replace the values with the parameter values you created and configured previously.


#Region 1
agent.environments[0].account-id=AWS_ACCOUNT_ID
agent.environments[0].agent-role-name=AWS_IAM_ROLE_NAME
agent.environments[0].access-key-id=AWS_IAM_ROLE_ACCESS_KEY
agent.environments[0].secret-access-id=AWS_IAM_ROLE_SECRET_KEY
agent.environments[0].bucket-name=AWS_S3_BUCKET_NAME
agent.environments[0].environment-name=AWS_REGION
agent.environments[0].region=AWS_REGION

#Region 2
agent.environments[1].account-id=AWS_ACCOUNT_ID
agent.environments[1].agent-role-name=AWS_IAM_ROLE_NAME
agent.environments[1].access-key-id=AWS_IAM_ROLE_ACCESS_KEY
agent.environments[1].secret-access-id=AWS_IAM_ROLE_SECRET_KEY
agent.environments[1].bucket-name=AWS_S3_BUCKET_NAME
agent.environments[1].environment-name=AWS_REGION
agent.environments[1].region=AWS_REGION

Warning Javascript is disabled or is unavailable in your browser.

To use the Amazon Web Services Documentation, Javascript must be enabled. Please refer to your browser's Help pages for instructions.

Document Conventions

Install a File Transfer agent

Create data transfer endpoints