Welcome to the Amazon Transfer Family API
Amazon Transfer Family is a secure transfer service that you can use to transfer files into and out of Amazon Simple Storage Service (Amazon S3) storage over the following protocols:
-
Secure Shell (SSH) File Transfer Protocol (SFTP)
-
File Transfer Protocol Secure (FTPS)
-
File Transfer Protocol (FTP)
-
Applicability Statement 2 (AS2)
File transfer protocols are used in data exchange workflows across different industries such as financial services, healthcare, advertising, and retail, among others. Amazon Transfer Family simplifies the migration of file transfer workflows to Amazon.
To use the Amazon Transfer Family service, you instantiate a server in the Amazon Region of your choice.
You can create the server, list available servers, and update and delete servers. The server
is the entity that requests file operations from Amazon Transfer Family. Servers have a number of
important properties. The server is a named instance as identified by a system assigned
ServerId
identifier. You can optionally assign a hostname, or even a custom
hostname to a server. The service bills for any instantiated servers (even ones
OFFLINE
), and for the amount of data transferred.
Users must be known to the server that requests file operations. A user as identified by
their username is assigned to a server. Usernames are used to authenticate requests. A
server can have only one authentication method: AWS_DIRECTORY_SERVICE
,
SERVICE_MANAGED
, AWS_LAMBDA
, or
API_GATEWAY
.
You can use any of the following identity provider types to authenticate users:
For
SERVICE_MANAGED
, an SSH public key is stored with the user's properties on a server. A user can have one or more SSH public keys on file for theSERVICE_MANAGED
authentication method. When a client requests a file operation forSERVICE_MANAGED
method, the client provides the username and SSH private key, which is authenticated, and access is provided.You can manage user authentication and access with your Microsoft Active Directory groups by selecting the
AWS_DIRECTORY_SERVICE
authentication method.-
You can connect to a custom identity provider by using Amazon Lambda. Choose the
AWS_LAMBDA
authentication method. You can also authenticate user requests using a custom authentication method that provides both user authentication and access. This method relies on the Amazon API Gateway to use your API call from your identity provider to validate user requests. This method is referred to as
API_GATEWAY
in API calls, and as Custom in the console. You might use this custom method to authenticate users against a directory service, a database name/password pair, or some other mechanism.
Users are assigned a policy with a trust relationship between themselves and an Amazon S3
bucket. They might be able to access all or part of a bucket. For a server to act on a
user's behalf, the server must inherit the trust relationship from the user. An
Amazon Identity and Access Management (IAM) role is created that contains the trust relationship, and that role is
assigned an AssumeRole
action. The server then can perform file operations as
if it were the user.
Users who have a home
directory property set will have that directory (or
folder) act as the target and source of file operations. When no home
directory
is set, the bucket's root
directory becomes the landing directory.
Servers, users, and roles are all identified by their Amazon Resource Name (ARN). You can assign tags, which are key-value pairs, to entities with an ARN. Tags are metadata that can be used to group or search for these entities. One example where tags are useful is for accounting purposes.
The following conventions are observed in Amazon Transfer Family ID formats:
-
ServerId
values take the forms-01234567890abcdef
. -
SshPublicKeyId
values take the formkey-01234567890abcdef
.
Amazon Resource Name (ARN) formats take the following form:
-
For servers, ARNs take the form
arn:aws-cn:transfer:
.region
:account-id
:server/server-id
An example of a server ARN is:
arn:aws-cn:transfer:us-east-1:123456789012:server/s-01234567890abcdef
. -
For users, ARNs take the form
arn:aws-cn:transfer:
.region
:account-id
:user/server-id
/username
An example is
arn:aws-cn:transfer:us-east-1:123456789012:user/s-01234567890abcdef/user1
.
DNS entries (endpoints) in use are as follows:
-
API endpoints take the form
transfer.
.region
.amazonaws.com -
Server endpoints take the form
server.transfer.
.region
.amazonaws.com
For a list of Transfer Family endpoints by Amazon Region, see the Amazon Transfer Family endpoints and quotas in the Amazon Web Services General Reference.
This API interface reference for Amazon Transfer Family contains documentation for a programming interface that you can use to manage Amazon Transfer Family. The reference structure is as follows:
-
For the alphabetical list of API actions, see Actions.
-
For the alphabetical list of data types, see Data Types.
-
For a list of common query parameters, see Common Parameters.
-
For descriptions of the error codes, see Common Errors.
Tip
Rather than actually running a command, you can use the
--generate-cli-skeleton
parameter with any API call to generate and display
a parameter template. You can then use the generated template to customize and use as input
on a later command. For details, see Generate and use a parameter skeleton file.