gateways

Creates, updates, deletes, gets or lists a gateways resource.

Overview

Name	gateways
Type	Resource
Id	aws.storagegateway.gateways

Fields

The following fields are returned by SELECT queries:

list_gateways

Name	Datatype	Description
deprecation_date	string	Date after which this gateway will not receive software updates for new features and bug fixes.
ec_2_instance_id	string	The ID of the Amazon EC2 instance that was used to launch the gateway.
ec_2_instance_region	string	The Amazon Web Services Region where the Amazon EC2 instance is located.
gateway_arn	string	The Amazon Resource Name (ARN) of the gateway. Use the ListGateways operation to return a list of gateways for your account and Amazon Web Services Region.
gateway_id	string	The unique identifier assigned to your gateway during activation. This ID becomes part of the gateway Amazon Resource Name (ARN), which you use as input for other operations.
gateway_name	string	The name of the gateway.
gateway_operational_state	string	The state of the gateway. Valid Values: DISABLED | ACTIVE
gateway_type	string	The type of the gateway. Amazon FSx File Gateway is no longer available to new customers. Existing customers of FSx File Gateway can continue to use the service normally. For capabilities similar to FSx File Gateway, visit this blog post.
host_environment	string	The type of hardware or software platform on which the gateway is running. Tape Gateway is no longer available on Snow Family devices. (VMWARE, HYPER-V, EC2, KVM, OTHER, SNOWBALL)
host_environment_id	string	A unique identifier for the specific instance of the host platform running the gateway. This value is only available for certain host environments, and its format depends on the host environment type.
software_version	string	The version number of the software running on the gateway appliance.

Methods

The following methods are available for this resource:

Name	Accessible by	Required Params	Optional Params	Description
list_gateways	select	region		Lists gateways owned by an Amazon Web Services account in an Amazon Web Services Region specified in the request. The returned list is ordered by gateway Amazon Resource Name (ARN). By default, the operation returns a maximum of 100 gateways. This operation supports pagination that allows you to optionally reduce the number of gateways returned in a response. If you have more gateways than are returned in a response (that is, the response returns only a truncated list of your gateways), the response contains a marker that you can specify in your next request to fetch the next page of gateways.
set_local_console_password	update	region, GatewayARN, LocalConsolePassword		Sets the password for your VM local console. When you log in to the local console for the first time, you log in to the VM with the default credentials. We recommend that you set a new password. You don't need to know the default password to set a new password.
set_smb_guest_password	update	region, GatewayARN, Password		Sets the password for the guest user smbguest. The smbguest user is the user when the authentication method for the file share is set to GuestAccess. This operation only supported for S3 File Gateways
update_smb_local_groups	update	region, GatewayARN, SMBLocalGroups		Updates the list of Active Directory users and groups that have special permissions for SMB file shares on the gateway.
update_smb_security_strategy	update	region, GatewayARN, SMBSecurityStrategy		Updates the SMB security strategy level for an Amazon S3 file gateway. This action is only supported for Amazon S3 file gateways. For information about configuring this setting using the Amazon Web Services console, see Setting a security level for your gateway in the Amazon S3 File Gateway User Guide. A higher security strategy level can affect performance of the gateway.
update_gateway_software_now	update	region, GatewayARN		Updates the gateway virtual machine (VM) software. The request immediately triggers the software update. When you make this request, you get a 200 OK success response immediately. However, it might take some time for the update to complete. You can call DescribeGatewayInformation to verify the gateway is in the STATE_RUNNING state. A software update forces a system restart of your gateway. You can minimize the chance of any disruption to your applications by increasing your iSCSI Initiators' timeouts. For more information about increasing iSCSI Initiator timeouts for Windows and Linux, see Customizing your Windows iSCSI settings and Customizing your Linux iSCSI settings, respectively.
delete_gateway	delete	region		Deletes a gateway. To specify which gateway to delete, use the Amazon Resource Name (ARN) of the gateway in your request. The operation deletes the gateway; however, it does not delete the gateway virtual machine (VM) from your host computer. After you delete a gateway, you cannot reactivate it. Completed snapshots of the gateway volumes are not deleted upon deleting the gateway, however, pending snapshots will not complete. After you delete a gateway, your next step is to remove it from your environment. You no longer pay software charges after the gateway is deleted; however, your existing Amazon EBS snapshots persist and you will continue to be billed for these snapshots. You can choose to remove all remaining Amazon EBS snapshots by canceling your Amazon EC2 subscription. If you prefer not to cancel your Amazon EC2 subscription, you can delete your snapshots using the Amazon EC2 console. For more information, see the Storage Gateway detail page.
activate_gateway	exec	region, ActivationKey, GatewayName, GatewayTimezone, GatewayRegion		Activates the gateway you previously deployed on your host. In the activation process, you specify information such as the Amazon Web Services Region that you want to use for storing snapshots or tapes, the time zone for scheduled snapshots the gateway snapshot schedule window, an activation key, and a name for your gateway. The activation process also associates your gateway with your account. For more information, see UpdateGatewayInformation. You must turn on the gateway VM before you can activate your gateway.
cancel_archival	exec	region, GatewayARN, TapeARN		Cancels archiving of a virtual tape to the virtual tape shelf (VTS) after the archiving process is initiated. This operation is only supported in the tape gateway type.
cancel_retrieval	exec	region, GatewayARN, TapeARN		Cancels retrieval of a virtual tape from the virtual tape shelf (VTS) to a gateway after the retrieval process is initiated. The virtual tape is returned to the VTS. This operation is only supported in the tape gateway type.
disable_gateway	exec	region, GatewayARN		Disables a tape gateway when the gateway is no longer functioning. For example, if your gateway VM is damaged, you can disable the gateway so you can recover virtual tapes. Use this operation for a tape gateway that is not reachable or not functioning. This operation is only supported in the tape gateway type. After a gateway is disabled, it cannot be enabled.
join_domain	exec	region, GatewayARN, DomainName, UserName, Password		Adds a file gateway to an Active Directory domain. This operation is only supported for file gateways that support the SMB file protocol. Joining a domain creates an Active Directory computer account in the default organizational unit, using the gateway's Gateway ID as the account name (for example, SGW-1234ADE). If your Active Directory environment requires that you pre-stage accounts to facilitate the join domain process, you will need to create this account ahead of time. To create the gateway's computer account in an organizational unit other than the default, you must specify the organizational unit when joining the domain.
retrieve_tape_archive	exec	region, TapeARN, GatewayARN		Retrieves an archived virtual tape from the virtual tape shelf (VTS) to a tape gateway. Virtual tapes archived in the VTS are not associated with any gateway. However after a tape is retrieved, it is associated with a gateway, even though it is also listed in the VTS, that is, archive. This operation is only supported in the tape gateway type. Once a tape is successfully retrieved to a gateway, it cannot be retrieved again to another gateway. You must archive the tape again before you can retrieve it to another gateway. This operation is only supported in the tape gateway type.
retrieve_tape_recovery_point	exec	region, TapeARN, GatewayARN		Retrieves the recovery point for the specified virtual tape. This operation is only supported in the tape gateway type. A recovery point is a point in time view of a virtual tape at which all the data on the tape is consistent. If your gateway crashes, virtual tapes that have recovery points can be recovered to a new gateway. The virtual tape can be retrieved to only one gateway. The retrieved tape is read-only. The virtual tape can be retrieved to only a tape gateway. There is no charge for retrieving recovery points.
shutdown_gateway	exec	region, GatewayARN		Shuts down a Tape Gateway or Volume Gateway. To specify which gateway to shut down, use the Amazon Resource Name (ARN) of the gateway in the body of your request. This API action cannot be used to shut down S3 File Gateway or FSx File Gateway. The operation shuts down the gateway service component running in the gateway's virtual machine (VM) and not the host VM. If you want to shut down the VM, it is recommended that you first shut down the gateway component in the VM to avoid unpredictable conditions. After the gateway is shutdown, you cannot call any other API except StartGateway, DescribeGatewayInformation, and ListGateways. For more information, see ActivateGateway. Your applications cannot read from or write to the gateway's storage volumes, and there are no snapshots taken. When you make a shutdown request, you will get a 200 OK success response immediately. However, it might take some time for the gateway to shut down. You can call the DescribeGatewayInformation API to check the status. For more information, see ActivateGateway. If do not intend to use the gateway again, you must delete the gateway (using DeleteGateway) to no longer pay software charges associated with the gateway.
start_availability_monitor_test	exec	region, GatewayARN		Start a test that verifies that the specified gateway is configured for High Availability monitoring in your host environment. This request only initiates the test and that a successful response only indicates that the test was started. It doesn't indicate that the test passed. For the status of the test, invoke the DescribeAvailabilityMonitorTest API. Starting this test will cause your gateway to go offline for a brief period.
start_gateway	exec	region, GatewayARN		Starts a gateway that you previously shut down (see ShutdownGateway). After the gateway starts, you can then make other API calls, your applications can read from or write to the gateway's storage volumes and you will be able to take snapshot backups. When you make a request, you will get a 200 OK success response immediately. However, it might take some time for the gateway to be ready. You should call DescribeGatewayInformation and check the status before making any additional API calls. For more information, see ActivateGateway. To specify which gateway to start, use the Amazon Resource Name (ARN) of the gateway in your request.

Parameters

Parameters can be passed in the WHERE clause of a query. Check the Methods section to see which parameters are required or optional for each operation.

Name	Datatype	Description
region	string	AWS region (default: us-east-1)

SELECT examples

list_gateways

Lists gateways owned by an Amazon Web Services account in an Amazon Web Services Region specified in the request. The returned list is ordered by gateway Amazon Resource Name (ARN). By default, the operation returns a maximum of 100 gateways. This operation supports pagination that allows you to optionally reduce the number of gateways returned in a response. If you have more gateways than are returned in a response (that is, the response returns only a truncated list of your gateways), the response contains a marker that you can specify in your next request to fetch the next page of gateways.

SELECT
deprecation_date,
ec_2_instance_id,
ec_2_instance_region,
gateway_arn,
gateway_id,
gateway_name,
gateway_operational_state,
gateway_type,
host_environment,
host_environment_id,
software_version
FROM aws.storagegateway.gateways
WHERE region = '{{ region }}' -- required
;

UPDATE examples

set_local_console_password

Sets the password for your VM local console. When you log in to the local console for the first time, you log in to the VM with the default credentials. We recommend that you set a new password. You don't need to know the default password to set a new password.

UPDATE aws.storagegateway.gateways
SET 
GatewayARN = '{{ GatewayARN }}',
LocalConsolePassword = '{{ LocalConsolePassword }}'
WHERE 
region = '{{ region }}' --required
AND GatewayARN = '{{ GatewayARN }}' --required
AND LocalConsolePassword = '{{ LocalConsolePassword }}' --required
RETURNING
gateway_arn;

set_smb_guest_password

Sets the password for the guest user smbguest. The smbguest user is the user when the authentication method for the file share is set to GuestAccess. This operation only supported for S3 File Gateways

UPDATE aws.storagegateway.gateways
SET 
GatewayARN = '{{ GatewayARN }}',
Password = '{{ Password }}'
WHERE 
region = '{{ region }}' --required
AND GatewayARN = '{{ GatewayARN }}' --required
AND Password = '{{ Password }}' --required
RETURNING
gateway_arn;

update_smb_local_groups

Updates the list of Active Directory users and groups that have special permissions for SMB file shares on the gateway.

UPDATE aws.storagegateway.gateways
SET 
GatewayARN = '{{ GatewayARN }}',
SMBLocalGroups = '{{ SMBLocalGroups }}'
WHERE 
region = '{{ region }}' --required
AND GatewayARN = '{{ GatewayARN }}' --required
AND SMBLocalGroups = '{{ SMBLocalGroups }}' --required
RETURNING
gateway_arn;

update_smb_security_strategy

Updates the SMB security strategy level for an Amazon S3 file gateway. This action is only supported for Amazon S3 file gateways. For information about configuring this setting using the Amazon Web Services console, see Setting a security level for your gateway in the Amazon S3 File Gateway User Guide. A higher security strategy level can affect performance of the gateway.

UPDATE aws.storagegateway.gateways
SET 
GatewayARN = '{{ GatewayARN }}',
SMBSecurityStrategy = '{{ SMBSecurityStrategy }}'
WHERE 
region = '{{ region }}' --required
AND GatewayARN = '{{ GatewayARN }}' --required
AND SMBSecurityStrategy = '{{ SMBSecurityStrategy }}' --required
RETURNING
gateway_arn;

update_gateway_software_now

Updates the gateway virtual machine (VM) software. The request immediately triggers the software update. When you make this request, you get a 200 OK success response immediately. However, it might take some time for the update to complete. You can call DescribeGatewayInformation to verify the gateway is in the STATE_RUNNING state. A software update forces a system restart of your gateway. You can minimize the chance of any disruption to your applications by increasing your iSCSI Initiators' timeouts. For more information about increasing iSCSI Initiator timeouts for Windows and Linux, see Customizing your Windows iSCSI settings and Customizing your Linux iSCSI settings, respectively.

UPDATE aws.storagegateway.gateways
SET 
GatewayARN = '{{ GatewayARN }}'
WHERE 
region = '{{ region }}' --required
AND GatewayARN = '{{ GatewayARN }}' --required
RETURNING
gateway_arn;

DELETE examples

delete_gateway

Deletes a gateway. To specify which gateway to delete, use the Amazon Resource Name (ARN) of the gateway in your request. The operation deletes the gateway; however, it does not delete the gateway virtual machine (VM) from your host computer. After you delete a gateway, you cannot reactivate it. Completed snapshots of the gateway volumes are not deleted upon deleting the gateway, however, pending snapshots will not complete. After you delete a gateway, your next step is to remove it from your environment. You no longer pay software charges after the gateway is deleted; however, your existing Amazon EBS snapshots persist and you will continue to be billed for these snapshots. You can choose to remove all remaining Amazon EBS snapshots by canceling your Amazon EC2 subscription. If you prefer not to cancel your Amazon EC2 subscription, you can delete your snapshots using the Amazon EC2 console. For more information, see the Storage Gateway detail page.

DELETE FROM aws.storagegateway.gateways
WHERE region = '{{ region }}' --required
;

Lifecycle Methods

activate_gateway

Activates the gateway you previously deployed on your host. In the activation process, you specify information such as the Amazon Web Services Region that you want to use for storing snapshots or tapes, the time zone for scheduled snapshots the gateway snapshot schedule window, an activation key, and a name for your gateway. The activation process also associates your gateway with your account. For more information, see UpdateGatewayInformation. You must turn on the gateway VM before you can activate your gateway.

EXEC aws.storagegateway.gateways.activate_gateway 
@region='{{ region }}' --required 
@@json=
'{
"ActivationKey": "{{ ActivationKey }}", 
"GatewayName": "{{ GatewayName }}", 
"GatewayTimezone": "{{ GatewayTimezone }}", 
"GatewayRegion": "{{ GatewayRegion }}", 
"GatewayType": "{{ GatewayType }}", 
"TapeDriveType": "{{ TapeDriveType }}", 
"MediumChangerType": "{{ MediumChangerType }}", 
"Tags": "{{ Tags }}"
}'
;

cancel_archival

Cancels archiving of a virtual tape to the virtual tape shelf (VTS) after the archiving process is initiated. This operation is only supported in the tape gateway type.

EXEC aws.storagegateway.gateways.cancel_archival 
@region='{{ region }}' --required 
@@json=
'{
"GatewayARN": "{{ GatewayARN }}", 
"TapeARN": "{{ TapeARN }}"
}'
;

cancel_retrieval

Cancels retrieval of a virtual tape from the virtual tape shelf (VTS) to a gateway after the retrieval process is initiated. The virtual tape is returned to the VTS. This operation is only supported in the tape gateway type.

EXEC aws.storagegateway.gateways.cancel_retrieval 
@region='{{ region }}' --required 
@@json=
'{
"GatewayARN": "{{ GatewayARN }}", 
"TapeARN": "{{ TapeARN }}"
}'
;

disable_gateway

Disables a tape gateway when the gateway is no longer functioning. For example, if your gateway VM is damaged, you can disable the gateway so you can recover virtual tapes. Use this operation for a tape gateway that is not reachable or not functioning. This operation is only supported in the tape gateway type. After a gateway is disabled, it cannot be enabled.

EXEC aws.storagegateway.gateways.disable_gateway 
@region='{{ region }}' --required 
@@json=
'{
"GatewayARN": "{{ GatewayARN }}"
}'
;

join_domain

Adds a file gateway to an Active Directory domain. This operation is only supported for file gateways that support the SMB file protocol. Joining a domain creates an Active Directory computer account in the default organizational unit, using the gateway's Gateway ID as the account name (for example, SGW-1234ADE). If your Active Directory environment requires that you pre-stage accounts to facilitate the join domain process, you will need to create this account ahead of time. To create the gateway's computer account in an organizational unit other than the default, you must specify the organizational unit when joining the domain.

EXEC aws.storagegateway.gateways.join_domain 
@region='{{ region }}' --required 
@@json=
'{
"GatewayARN": "{{ GatewayARN }}", 
"DomainName": "{{ DomainName }}", 
"OrganizationalUnit": "{{ OrganizationalUnit }}", 
"DomainControllers": "{{ DomainControllers }}", 
"TimeoutInSeconds": {{ TimeoutInSeconds }}, 
"UserName": "{{ UserName }}", 
"Password": "{{ Password }}"
}'
;

retrieve_tape_archive

Retrieves an archived virtual tape from the virtual tape shelf (VTS) to a tape gateway. Virtual tapes archived in the VTS are not associated with any gateway. However after a tape is retrieved, it is associated with a gateway, even though it is also listed in the VTS, that is, archive. This operation is only supported in the tape gateway type. Once a tape is successfully retrieved to a gateway, it cannot be retrieved again to another gateway. You must archive the tape again before you can retrieve it to another gateway. This operation is only supported in the tape gateway type.

EXEC aws.storagegateway.gateways.retrieve_tape_archive 
@region='{{ region }}' --required 
@@json=
'{
"TapeARN": "{{ TapeARN }}", 
"GatewayARN": "{{ GatewayARN }}"
}'
;

retrieve_tape_recovery_point

Retrieves the recovery point for the specified virtual tape. This operation is only supported in the tape gateway type. A recovery point is a point in time view of a virtual tape at which all the data on the tape is consistent. If your gateway crashes, virtual tapes that have recovery points can be recovered to a new gateway. The virtual tape can be retrieved to only one gateway. The retrieved tape is read-only. The virtual tape can be retrieved to only a tape gateway. There is no charge for retrieving recovery points.

EXEC aws.storagegateway.gateways.retrieve_tape_recovery_point 
@region='{{ region }}' --required 
@@json=
'{
"TapeARN": "{{ TapeARN }}", 
"GatewayARN": "{{ GatewayARN }}"
}'
;

shutdown_gateway

Shuts down a Tape Gateway or Volume Gateway. To specify which gateway to shut down, use the Amazon Resource Name (ARN) of the gateway in the body of your request. This API action cannot be used to shut down S3 File Gateway or FSx File Gateway. The operation shuts down the gateway service component running in the gateway's virtual machine (VM) and not the host VM. If you want to shut down the VM, it is recommended that you first shut down the gateway component in the VM to avoid unpredictable conditions. After the gateway is shutdown, you cannot call any other API except StartGateway, DescribeGatewayInformation, and ListGateways. For more information, see ActivateGateway. Your applications cannot read from or write to the gateway's storage volumes, and there are no snapshots taken. When you make a shutdown request, you will get a 200 OK success response immediately. However, it might take some time for the gateway to shut down. You can call the DescribeGatewayInformation API to check the status. For more information, see ActivateGateway. If do not intend to use the gateway again, you must delete the gateway (using DeleteGateway) to no longer pay software charges associated with the gateway.

EXEC aws.storagegateway.gateways.shutdown_gateway 
@region='{{ region }}' --required 
@@json=
'{
"GatewayARN": "{{ GatewayARN }}"
}'
;

start_availability_monitor_test

Start a test that verifies that the specified gateway is configured for High Availability monitoring in your host environment. This request only initiates the test and that a successful response only indicates that the test was started. It doesn't indicate that the test passed. For the status of the test, invoke the DescribeAvailabilityMonitorTest API. Starting this test will cause your gateway to go offline for a brief period.

EXEC aws.storagegateway.gateways.start_availability_monitor_test 
@region='{{ region }}' --required 
@@json=
'{
"GatewayARN": "{{ GatewayARN }}"
}'
;

start_gateway

Starts a gateway that you previously shut down (see ShutdownGateway). After the gateway starts, you can then make other API calls, your applications can read from or write to the gateway's storage volumes and you will be able to take snapshot backups. When you make a request, you will get a 200 OK success response immediately. However, it might take some time for the gateway to be ready. You should call DescribeGatewayInformation and check the status before making any additional API calls. For more information, see ActivateGateway. To specify which gateway to start, use the Amazon Resource Name (ARN) of the gateway in your request.

EXEC aws.storagegateway.gateways.start_gateway 
@region='{{ region }}' --required 
@@json=
'{
"GatewayARN": "{{ GatewayARN }}"
}'
;