2020/01/10 - AWS Transfer for SFTP - 4 updated api methods
Changes This release introduces a new endpoint type that allows you to attach Elastic IP addresses from your AWS account with your server's endpoint directly and whitelist access to your server by client's internet IP address(es) using VPC Security Groups.
{'EndpointDetails': {'AddressAllocationIds': ['string'],
'SubnetIds': ['string'],
'VpcId': 'string'},
'EndpointType': {'VPC'}}
Instantiates an autoscaling virtual server based on Secure File Transfer Protocol (SFTP) in AWS. When you make updates to your server or when you work with users, use the service-generated ServerId property that is assigned to the newly created server.
See also: AWS API Documentation
Request Syntax
client.create_server(
EndpointDetails={
'AddressAllocationIds': [
'string',
],
'SubnetIds': [
'string',
],
'VpcEndpointId': 'string',
'VpcId': 'string'
},
EndpointType='PUBLIC'|'VPC'|'VPC_ENDPOINT',
HostKey='string',
IdentityProviderDetails={
'Url': 'string',
'InvocationRole': 'string'
},
IdentityProviderType='SERVICE_MANAGED'|'API_GATEWAY',
LoggingRole='string',
Tags=[
{
'Key': 'string',
'Value': 'string'
},
]
)
dict
The virtual private cloud (VPC) endpoint settings that are configured for your SFTP server. With a VPC endpoint, you can restrict access to your SFTP server to resources only within your VPC. To control incoming internet traffic, you will need to invoke the UpdateServer API and attach an Elastic IP to your server's endpoint.
AddressAllocationIds (list) --
A list of address allocation IDs that are required to attach an Elastic IP address to your SFTP server's endpoint. This is only valid in the UpdateServer API.
Note
This property can only be use when EndpointType is set to VPC .
(string) --
SubnetIds (list) --
A list of subnet IDs that are required to host your SFTP server endpoint in your VPC.
(string) --
VpcEndpointId (string) --
The ID of the VPC endpoint.
VpcId (string) --
The VPC ID of the virtual private cloud in which the SFTP server's endpoint will be hosted.
string
The type of VPC endpoint that you want your SFTP server to connect to. You can choose to connect to the public internet or a virtual private cloud (VPC) endpoint. With a VPC endpoint, you can restrict access to your SFTP server and resources only within your VPC.
string
The RSA private key as generated by the ssh-keygen -N "" -f my-new-server-key command.
Warning
If you aren't planning to migrate existing users from an existing SFTP server to a new AWS SFTP server, don't update the host key. Accidentally changing a server's host key can be disruptive.
For more information, see "https://alpha-docs-aws.amazon.com/transfer/latest/userguide/configuring-servers.html#change-host-key" in the AWS SFTP User Guide.
dict
This parameter is required when the IdentityProviderType is set to API_GATEWAY . Accepts an array containing all of the information required to call a customer-supplied authentication API, including the API Gateway URL. This property is not required when the IdentityProviderType is set to SERVICE_MANAGED .
Url (string) --
The Url parameter provides contains the location of the service endpoint used to authenticate users.
InvocationRole (string) --
The InvocationRole parameter provides the type of InvocationRole used to authenticate the user account.
string
Specifies the mode of authentication for the SFTP server. The default value is SERVICE_MANAGED , which allows you to store and access SFTP user credentials within the AWS Transfer for SFTP service. Use the API_GATEWAY value to integrate with an identity provider of your choosing. The API_GATEWAY setting requires you to provide an API Gateway endpoint URL to call for authentication using the IdentityProviderDetails parameter.
string
A value that allows the service to write your SFTP users' activity to your Amazon CloudWatch logs for monitoring and auditing purposes.
list
Key-value pairs that can be used to group and search for servers.
(dict) --
Creates a key-value pair for a specific resource. Tags are metadata that you can use to search for and group a resource for various purposes. You can apply tags to servers, users, and roles. A tag key can take more than one value. For example, to group servers for accounting purposes, you might create a tag called Group and assign the values Research and Accounting to that group.
Key (string) -- [REQUIRED]
The name assigned to the tag that you create.
Value (string) -- [REQUIRED]
This property contains one or more values that you assigned to the key name you create.
dict
Response Syntax
{
'ServerId': 'string'
}
Response Structure
(dict) --
ServerId (string) --
The service-assigned ID of the SFTP server that is created.
{'Server': {'EndpointDetails': {'AddressAllocationIds': ['string'],
'SubnetIds': ['string'],
'VpcId': 'string'},
'EndpointType': {'VPC'}}}
Describes the server that you specify by passing the ServerId parameter.
The response contains a description of the server's properties. When you set EndpointType to VPC, the response will contain the EndpointDetails .
See also: AWS API Documentation
Request Syntax
client.describe_server(
ServerId='string'
)
string
[REQUIRED]
A system-assigned unique identifier for an SFTP server.
dict
Response Syntax
{
'Server': {
'Arn': 'string',
'EndpointDetails': {
'AddressAllocationIds': [
'string',
],
'SubnetIds': [
'string',
],
'VpcEndpointId': 'string',
'VpcId': 'string'
},
'EndpointType': 'PUBLIC'|'VPC'|'VPC_ENDPOINT',
'HostKeyFingerprint': 'string',
'IdentityProviderDetails': {
'Url': 'string',
'InvocationRole': 'string'
},
'IdentityProviderType': 'SERVICE_MANAGED'|'API_GATEWAY',
'LoggingRole': 'string',
'ServerId': 'string',
'State': 'OFFLINE'|'ONLINE'|'STARTING'|'STOPPING'|'START_FAILED'|'STOP_FAILED',
'Tags': [
{
'Key': 'string',
'Value': 'string'
},
],
'UserCount': 123
}
}
Response Structure
(dict) --
Server (dict) --
An array containing the properties of the server with the ServerID you specified.
Arn (string) --
Specifies the unique Amazon Resource Name (ARN) for the server to be described.
EndpointDetails (dict) --
The virtual private cloud (VPC) endpoint settings that you configured for your SFTP server.
AddressAllocationIds (list) --
A list of address allocation IDs that are required to attach an Elastic IP address to your SFTP server's endpoint. This is only valid in the UpdateServer API.
Note
This property can only be use when EndpointType is set to VPC .
(string) --
SubnetIds (list) --
A list of subnet IDs that are required to host your SFTP server endpoint in your VPC.
(string) --
VpcEndpointId (string) --
The ID of the VPC endpoint.
VpcId (string) --
The VPC ID of the virtual private cloud in which the SFTP server's endpoint will be hosted.
EndpointType (string) --
The type of endpoint that your SFTP server is connected to. If your SFTP server is connected to a VPC endpoint, your server isn't accessible over the public internet.
HostKeyFingerprint (string) --
This value contains the message-digest algorithm (MD5) hash of the server's host key. This value is equivalent to the output of the ssh-keygen -l -E md5 -f my-new-server-key command.
IdentityProviderDetails (dict) --
Specifies information to call a customer-supplied authentication API. This field is not populated when the IdentityProviderType of the server is SERVICE_MANAGED >.
Url (string) --
The Url parameter provides contains the location of the service endpoint used to authenticate users.
InvocationRole (string) --
The InvocationRole parameter provides the type of InvocationRole used to authenticate the user account.
IdentityProviderType (string) --
This property defines the mode of authentication method enabled for this service. A value of SERVICE_MANAGED means that you are using this server to store and access SFTP user credentials within the service. A value of API_GATEWAY indicates that you have integrated an API Gateway endpoint that will be invoked for authenticating your user into the service.
LoggingRole (string) --
This property is an AWS Identity and Access Management (IAM) entity that allows the server to turn on Amazon CloudWatch logging for Amazon S3 events. When set, user activity can be viewed in your CloudWatch logs.
ServerId (string) --
This property is a unique system-assigned identifier for the SFTP server that you instantiate.
State (string) --
The condition of the SFTP server for the server that was described. A value of ONLINE indicates that the server can accept jobs and transfer files. A State value of OFFLINE means that the server cannot perform file transfer operations.
The states of STARTING and STOPPING indicate that the server is in an intermediate state, either not fully able to respond, or not fully offline. The values of START_FAILED or STOP_FAILED can indicate an error condition.
Tags (list) --
This property contains the key-value pairs that you can use to search for and group servers that were assigned to the server that was described.
(dict) --
Creates a key-value pair for a specific resource. Tags are metadata that you can use to search for and group a resource for various purposes. You can apply tags to servers, users, and roles. A tag key can take more than one value. For example, to group servers for accounting purposes, you might create a tag called Group and assign the values Research and Accounting to that group.
Key (string) --
The name assigned to the tag that you create.
Value (string) --
This property contains one or more values that you assigned to the key name you create.
UserCount (integer) --
The number of users that are assigned to the SFTP server you specified with the ServerId .
{'Servers': {'EndpointType': {'VPC'}}}
Lists the Secure File Transfer Protocol (SFTP) servers that are associated with your AWS account.
See also: AWS API Documentation
Request Syntax
client.list_servers(
MaxResults=123,
NextToken='string'
)
integer
Specifies the number of servers to return as a response to the ListServers query.
string
When additional results are obtained from the ListServers command, a NextToken parameter is returned in the output. You can then pass the NextToken parameter in a subsequent command to continue listing additional servers.
dict
Response Syntax
{
'NextToken': 'string',
'Servers': [
{
'Arn': 'string',
'IdentityProviderType': 'SERVICE_MANAGED'|'API_GATEWAY',
'EndpointType': 'PUBLIC'|'VPC'|'VPC_ENDPOINT',
'LoggingRole': 'string',
'ServerId': 'string',
'State': 'OFFLINE'|'ONLINE'|'STARTING'|'STOPPING'|'START_FAILED'|'STOP_FAILED',
'UserCount': 123
},
]
}
Response Structure
(dict) --
NextToken (string) --
When you can get additional results from the ListServers operation, a NextToken parameter is returned in the output. In a following command, you can pass in the NextToken parameter to continue listing additional servers.
Servers (list) --
An array of servers that were listed.
(dict) --
Returns properties of the server that was specified.
Arn (string) --
The unique Amazon Resource Name (ARN) for the server to be listed.
IdentityProviderType (string) --
The authentication method used to validate a user for the server that was specified. This can include Secure Shell (SSH), user name and password combinations, or your own custom authentication method. Valid values include SERVICE_MANAGED or API_GATEWAY .
EndpointType (string) --
The type of VPC endpoint that your SFTP server is connected to. If your SFTP server is connected to a VPC endpoint, your server isn't accessible over the public internet.
LoggingRole (string) --
The AWS Identity and Access Management entity that allows the server to turn on Amazon CloudWatch logging.
ServerId (string) --
This value is the unique system assigned identifier for the SFTP servers that were listed.
State (string) --
This property describes the condition of the SFTP server for the server that was described. A value of ONLINE > indicates that the server can accept jobs and transfer files. A State value of OFFLINE means that the server cannot perform file transfer operations.
The states of STARTING and STOPPING indicate that the server is in an intermediate state, either not fully able to respond, or not fully offline. The values of START_FAILED or STOP_FAILED can indicate an error condition.
UserCount (integer) --
This property is a numeric value that indicates the number of users that are assigned to the SFTP server you specified with the ServerId .
{'EndpointDetails': {'AddressAllocationIds': ['string'],
'SubnetIds': ['string'],
'VpcId': 'string'},
'EndpointType': {'VPC'}}
Updates the server properties after that server has been created.
The UpdateServer call returns the ServerId of the Secure File Transfer Protocol (SFTP) server you updated.
See also: AWS API Documentation
Request Syntax
client.update_server(
EndpointDetails={
'AddressAllocationIds': [
'string',
],
'SubnetIds': [
'string',
],
'VpcEndpointId': 'string',
'VpcId': 'string'
},
EndpointType='PUBLIC'|'VPC'|'VPC_ENDPOINT',
HostKey='string',
IdentityProviderDetails={
'Url': 'string',
'InvocationRole': 'string'
},
LoggingRole='string',
ServerId='string'
)
dict
The virtual private cloud (VPC) endpoint settings that are configured for your SFTP server. With a VPC endpoint, you can restrict access to your SFTP server to resources only within your VPC. To control incoming internet traffic, you will need to associate one or more Elastic IP addresses with your server's endpoint.
AddressAllocationIds (list) --
A list of address allocation IDs that are required to attach an Elastic IP address to your SFTP server's endpoint. This is only valid in the UpdateServer API.
Note
This property can only be use when EndpointType is set to VPC .
(string) --
SubnetIds (list) --
A list of subnet IDs that are required to host your SFTP server endpoint in your VPC.
(string) --
VpcEndpointId (string) --
The ID of the VPC endpoint.
VpcId (string) --
The VPC ID of the virtual private cloud in which the SFTP server's endpoint will be hosted.
string
The type of endpoint that you want your SFTP server to connect to. You can choose to connect to the public internet or a virtual private cloud (VPC) endpoint. With a VPC endpoint, your SFTP server isn't accessible over the public internet.
string
The RSA private key as generated by ssh-keygen -N "" -f my-new-server-key .
Warning
If you aren't planning to migrate existing users from an existing SFTP server to a new AWS SFTP server, don't update the host key. Accidentally changing a server's host key can be disruptive.
For more information, see "https://docs.aws.amazon.com/transfer/latest/userguide/configuring-servers.html#change-host-key" in the AWS SFTP User Guide.
dict
This response parameter is an array containing all of the information required to call a customer's authentication API method.
Url (string) --
The Url parameter provides contains the location of the service endpoint used to authenticate users.
InvocationRole (string) --
The InvocationRole parameter provides the type of InvocationRole used to authenticate the user account.
string
A value that changes the AWS Identity and Access Management (IAM) role that allows Amazon S3 events to be logged in Amazon CloudWatch, turning logging on or off.
string
[REQUIRED]
A system-assigned unique identifier for an SFTP server instance that the user account is assigned to.
dict
Response Syntax
{
'ServerId': 'string'
}
Response Structure
(dict) --
ServerId (string) --
A system-assigned unique identifier for an SFTP server that the user account is assigned to.