Adds a DNAT entry to a DNAT table.

Description

Each DNAT entry consists of the following parameters: ExternalIp, ExternalPort, IpProtocol, InternalIp, and InternalPort. After you add a DNAT entry, the NAT gateway forwards packets of the specified protocol from ExternalIp:ExternalPort to InternalIp:InternalPort and sends responses back through the same route.

When you call this operation, take note of the following limits:

  • CreateForwardEntry is an asynchronous operation. After you make a request, a DNAT entry ID is returned but the specified DNAT entry is not added. The system adds the entry in the background. You can call the DescribeForwardTableEntries operation to query the status of a DNAT entry.
    • If the DNAT entry is in the Pending state, the system is adding the DNAT entry. You can only query the status of the DNAT entry, but cannot perform other operations.
    • If the DNAT entry is in the Available state, the DNAT entry is added.
  • You cannot repeatedly call the CreateForwardEntry operation to add a DNAT entry within the specified period of time.
  • All combinations of ExternalIp, ExternalPort, and IpProtocol used in DNAT entries must be unique. You cannot distribute requests to more than one Elastic Compute Service (ECS) instance if these requests are initiated from the same source IP address, received on the same port, and use the same protocol.
  • The combinations of IpProtocol, InternalIp, and InternalPort must be unique.
  • If one or more DNAT entries in the DNAT table are in the Pending or Modifying state, you cannot add DNAT entries to the DNAT table.
  • You can add at most 100 DNAT entries to a DNAT table.
  • For an elastic IP address (EIP) used by an Internet NAT gateway or a NAT IP address used by a Virtual Private Cloud (VPC) NAT gateway, take note of the following limit: If the IP address has IP mapping enabled and is specified in a DNAT entry, the IP address cannot be used by another DNAT or SNAT entry.

Debugging

OpenAPI Explorer automatically calculates the signature value. For your convenience, we recommend that you call this operation in OpenAPI Explorer. OpenAPI Explorer dynamically generates the sample code of the operation for different SDKs.

Request parameters

Parameter Type Required Example Description
Action String Yes CreateForwardEntry

The operation that you want to perform. Set the value to CreateForwardEntry.

RegionId String Yes cn-hangzhou

The region ID of the NAT gateway.

You can call the DescribeRegions operation to query the most recent region list.

ForwardTableId String Yes ftb-bp1mbjubq34hlcqpa****

The ID of the DNAT table.

ExternalIp String Yes 116.28.XX.XX
  • The EIP that can be accessed over the Internet when you configure a DNAT entry for an Internet NAT gateway.
  • The NAT IP address that can be accessed by external networks when you configure a DNAT entry for a VPC NAT gateway.
ExternalPort String Yes 8080
  • The external port range that is used for port forwarding when you configure a DNAT entry for an Internet NAT gateway.
    • Valid values: 1 to 65535.
    • To specify a port range, separate the first port and the last port with a forward slash (/), for example, 10/20.
    • If you set ExternalPort to a port range, you must also set InternalPort to a port range, and the number of ports specified by these parameters must be the same. For example, if you set ExternalPort to 10/20, you can set InternalPort to 80/90.
  • The port that can be accessed by external networks when you configure a DNAT entry for a VPC NAT gateway. Valid values: 1 to 65535.
InternalIp String Yes 192.168.XX.XX
  • The private IP address of the ECS instance that needs to communicate with the Internet when you configure a DNAT entry for an Internet NAT gateway. The private IP address must meet the following requirements:
    • It must belong to the CIDR block of the VPC where the NAT gateway is deployed.
    • The DNAT entry takes effect only if the private IP address is assigned to an ECS instance and the ECS instance is not associated with an EIP.
  • The private IP address that uses DNAT when you add a DNAT entry to a VPC NAT gateway.
InternalPort String Yes 80
  • The internal port or port range that is used for port forwarding when you configure a DNAT entry for an Internet NAT gateway. Valid values: 1 to 65535.
  • The port of the destination ECS instance to be mapped when you configure a DNAT entry for a VPC NAT gateway. Valid values: 1 to 65535.
IpProtocol String Yes TCP

The protocol. Valid values:

  • TCP: The NAT gateway forwards TCP packets.
  • UDP: The NAT gateway forwards UDP packets.
  • Any: The NAT gateway forwards packets of all protocols. If you set IpProtocol to Any, you must also set ExternalPort and InternalPort to Any to implement DNAT IP mapping.
ForwardEntryName String No ForwardEntry-1

The name of the DNAT entry.

The name must be 2 to 128 characters in length. It must start with a letter but cannot start with http:// or https://.

ClientToken String No 0c593ea1-3bea-11e9-b96b-88e9fe6****

The client token that is used to ensure the idempotence of the request.

You can use the client to generate the value, but you must make sure that it is unique among different requests. The client token can contain only ASCII characters.

Note If you do not set this parameter, the system automatically uses RequestId as ClientToken. The value of RequestId in each API request may be different.
PortBreak Boolean No false

Specifies whether to remove limits on the port range. Valid values:

  • true: yes
  • false (default): no
Note If an SNAT entry and a DNAT entry use the same public IP address, and you want to specify a port number greater than 1024, set Portbreak to true.

Response parameters

Parameter Type Example Description
ForwardEntryId String fwd-119smw5tkasdf****

The ID of the DNAT entry.

RequestId String A4AEE536-A97A-40EB-9EBE-53A6948A6928

The ID of the request.

Examples

Sample requests

http(s)://[Endpoint]/?Action=CreateForwardEntry
&RegionId=cn-hangzhou
&ForwardTableId=ftb-bp1mbjubq34hlcqpa****
&ExternalIp=116.28.XX.XX
&ExternalPort=8080
&InternalIp=192.168.XX.XX
&InternalPort=80
&IpProtocol=TCP
&ForwardEntryName=ForwardEntry-1
&ClientToken=0c593ea1-3bea-11e9-b96b-88e9fe6****
&PortBreak=false
&Common request parameters

Sample success responses

XML format 

HTTP/1.1 200 OK
Content-Type:application/xml

<CreateForwardEntryResponse>
    <ForwardEntryId>fwd-119smw5tkasdf****</ForwardEntryId>
    <RequestId>A4AEE536-A97A-40EB-9EBE-53A6948A6928</RequestId>
</CreateForwardEntryResponse>

JSON format 

HTTP/1.1 200 OK
Content-Type:application/json

{
  "ForwardEntryId" : "fwd-119smw5tkasdf****",
  "RequestId" : "A4AEE536-A97A-40EB-9EBE-53A6948A6928"
}

Error codes

HttpCode Error code Error message Description
400 ExclusiveParam.%sAnd%s The param of %s and %s are mutually exclusive. You cannot set %s and %s at the same time.
400 OperationUnsupported.ForwardEntry Duplicated destination ip port is unsupported. The error message returned because duplicate IP addresses and ports are not supported.
400 InvalidIp.NotInNatgw The specified Ip not belong to natgateway. The error message returned because the specified EIP is not associated with the NAT gateway.
400 IncorrectStatus.NatIp The status of %s [%s] is incorrect. The error message returned because the status of the NAT IP address is invalid.
400 InvalidExternalIp.Malformed The specified ExternalIp is not a valid IP address. The error message returned because the specified EIP is invalid.
400 InvalidInternalIp.Malformed The specified InternalIp is not a valid IP address. The error message returned because the specified destination private IP address is invalid.
400 InvalidExternalPort.Malformed The specified ExternalPort is not a valid port. The error message returned because the specified public port is invalid.
400 InvalidInternalPort.Malformed The specified InternalPort is not a valid port. The error message returned because the specified private port is invalid.
400 Forbidden.DestnationIpOutOfVpcCIDR The specified Internal Ip is Out of VPC CIDR. The error message returned because the specified private IP address does not fall within the CIDR block of the VPC. Enter a private IP address that falls within the CIDR block of the VPC.
400 InvalidProtocal.ValueNotSupported The specified IpProtocol does not support. The error message returned because the specified protocol is not supported.
400 IncorretForwardEntryStatus Some Forward entry status blocked this operation.. The error message returned because you are not authorized to perform the specified operation. The error message returned because one or more DNAT entries in the DNAT table are in the Pending or Modifying state.
400 Forbidden.ExternalIp.UsedInSnatTable The specified ExternalIp is already used in SnatTable The error message returned because the specified EIP is already used by an SNAT entry. Select a different EIP or delete the SNAT entry.
400 Forbindden The specified Instance already bind eip The error message returned because the ECS instance is associated with an EIP. Disassociate the EIP from the ECS instance before you create forwarding rules.
400 Forbidden.InternalIpOutOfVpcCIDR The specified Internal Ip is Out of VPC CIDR. The error message returned because the private IP address does not fall within the CIDR block of the VPC.
400 Invalid.natgwNotExist The specified natgateway not exist. The error message returned because the specified NAT gateway does not exist.
400 MissingParameter Missing mandatory parameter The error message returned because required parameters are not set. Check whether you have set all required parameters before you call this operation.
400 InvalidParameter.Name.Malformed The specified Name is not valid. The error message returned because the specified name format is invalid. Enter the name in the valid format.
400 IncorrectStatus.ForwardEntry The status of %s [%s] is incorrect. The error message returned because the DNAT entry to be deleted is in an invalid state.
404 ResourceNotFound.NatIp The specified resource of %s is not found. The error message returned because the NAT IP address is not found.
404 InvalidRegionId.NotFound The specified RegionId does not exist in our records. The error message returned because the specified region ID does not exist.
404 InvalidForwardTableId.NotFound Specified forward table does not exist. The error message returned because the specified DNAT table does not exist. Check the parameter and try again.
404 InvalidExternalIp.NotFound Specified External Ip address does not found on the VRouter The error message returned because the specified EIP does not exist.
500 InternalError The request processing has failed due to some unknown error. The error message returned because some unknown errors occurred.

For a list of error codes, visit the Error Center.