All Products
Search

This Product

    Virtual Private Cloud:CreateForwardEntry

    Document Center

    Virtual Private Cloud:CreateForwardEntry

    Last Updated:Aug 29, 2024

    Adds a DNAT entry to a DNAT table.

    Operation 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 over 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 a request is sent, the system returns a request ID and runs the task in the background. You can call the DescribeForwardTableEntries operation to query the status of the task.

      • If the DNAT entry is in the Pending state, the system is adding the DNAT entry. You can only query 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 a specific 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.

    Authorization information

    The following table shows the authorization information corresponding to the API. The authorization information can be used in the Action policy element to grant a RAM user or RAM role the permissions to call this API operation. Description:

    • Operation: the value that you can use in the Action element to specify the operation on a resource.
    • Access level: the access level of each operation. The levels are read, write, and list.
    • Resource type: the type of the resource on which you can authorize the RAM user or the RAM role to perform the operation. Take note of the following items:
      • The required resource types are displayed in bold characters.
      • If the permissions cannot be granted at the resource level, All Resources is used in the Resource type column of the operation.
    • Condition Key: the condition key that is defined by the cloud service.
    • Associated operation: other operations that the RAM user or the RAM role must have permissions to perform to complete the operation. To complete the operation, the RAM user or the RAM role must have the permissions to perform the associated operations.
    OperationAccess levelResource typeCondition keyAssociated operation
    vpc:CreateForwardEntrycreate
    • ForwardTable
      acs:vpc:{#regionId}:{#accountId}:forwardtable/{#ForwardTableId}
      none
    		none

    Request parameters

    ParameterTypeRequiredDescriptionExample
    RegionIdstringYes

    The region ID of the NAT gateway.

    You can call the DescribeRegions operation to obtain the region ID.

    		cn-hangzhou
    ForwardTableIdstringYes

    The ID of the DNAT table.

    		ftb-bp1mbjubq34hlcqpa****
    ExternalIpstringYes
    • 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.
    		116.28.XX.XX
    ExternalPortstringYes

    • 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.

    		8080
    InternalIpstringYes

    • 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.

    		192.168.XX.XX
    InternalPortstringYes
    • 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.
    		80
    IpProtocolstringYes

    The protocol. Valid values:

    • TCP
    • UDP
    • Any If you set IpProtocol to Any, you must also set ExternalPort and InternalPort to Any to implement DNAT IP mapping.
    		TCP
    ForwardEntryNamestringNo

    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://.

    		ForwardEntry-1
    ClientTokenstringNo

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

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

    Note If you do not specify this parameter, the system automatically uses the request ID as the client token. The request ID may be different for each request.
    		0c593ea1-3bea-11e9-b96b-88e9fe6****
    PortBreakbooleanNo

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

    • true
    • false (default)
    Note If a DNAT entry and an SNAT entry have the same public IP address, ou must specify a port that is larger that 1024, and set PortBreak to true.
    		false

    Response parameters

    ParameterTypeDescriptionExample
    object
    ForwardEntryIdstring

    The ID of the DNAT entry.

    		fwd-119smw5tkasdf****
    RequestIdstring

    The request ID.

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

    Examples

    Sample success responses

    JSONformat

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

    Error codes

    HTTP status codeError codeError messageDescription
    400UnsupportedFeature.PrivateLinkEnabledThe feature of PrivateLinkEnabled is not supported.-
    400UnsupportedFeature.PortSegmentThe feature of PortSegment is not supported.-
    400ExclusiveParam.%sAnd%sThe param of %s and %s are mutually exclusive.You cannot specify %s and %s at the same time.
    400DuplicatedParam.InternalPortThe param of %s is duplicated.Duplicate parameters are specified for %s.
    400DuplicatedParam.ExternalPortThe param of %s is duplicated.Duplicate parameters are specified for %s.
    400OperationFailed.AnyPortConfigOperation failed because any port correspondence any protocolThe operation failed because any port corresponds to any protocol.
    400OperationUnsupported.ForwardEntryDuplicated destination ip port is unsupported.You cannot specify duplicate destination IP addresses or destination ports.
    400InvalidIp.NotInNatgwThe specified Ip not belong to natgateway.The specified EIP is not associated with the NAT gateway.
    400QuotaExceeded.ForwardEntryThe quota of %s is exceeded, usage %s/%s.-
    400IncorrectStatus.NatIpThe status of %s [%s] is incorrect.The status of NatIp is incorrect.
    400Forbidden.IpHasBeenUsedInSnatThe source ip can't be used. Because it has been used in snat.-
    400InvalidExternalIp.MalformedThe specified ExternalIp is not a valid IP address.The specified EIP is invalid.
    400InvalidInternalIp.MalformedThe specified InternalIp is not a valid IP address.The specified destination private IP address is invalid.
    400InvalidExternalPort.MalformedThe specified ExternalPort is not a valid port.The specified public port is invalid.
    400InvalidInternalPort.MalformedThe specified InternalPort is not a valid port.The specified private port is invalid.
    400Forbidden.DestnationIpOutOfVpcCIDRThe specified Internal Ip is Out of VPC CIDR.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.
    400Forbidden.DestinationIpOutOfVswitchCIDRThe specified Internal Ip is Out of VSwitch CIDR.-
    400InvalidProtocal.ValueNotSupportedThe specified IpProtocol does not support.The specified protocol is not supported.
    400IncorretForwardEntryStatusSome Forward entry status blocked this operation..The operation is not supported because one or more DNAT entries in the DNAT table are in the Pending or Modifying state.
    400QuotaExceeded.ForwardEntryForward entry quota exceeded in this route table.-
    400ForwardEntry.DuplicatedThe specified ExternalIp, IpProtocol, ExternalPort,InternalIp, InternalPort is duplicated-
    400Forbidden.ExternalIp.UsedInSnatTableThe specified ExternalIp is already used in SnatTableThe specified EIP is already used by an SNAT entry. Select a different EIP or delete the SNAT entry.
    400ForbinddenThe specified Instance already bind eipThe ECS instance is associated with an EIP. Disassociate the EIP from the ECS instance before you create forwarding rules.
    400Forbidden.InternalIpOutOfVpcCIDRThe specified Internal Ip is Out of VPC CIDR.The private IP address does not fall within the CIDR block of the VPC.
    400Invalid.natgwNotExistThe specified natgateway not exist.The specified NAT gateway does not exist.
    400MissingParameterMissing mandatory parameterRequired parameters are not specified. Check whether you have specified all required parameters before you call this operation.
    400AnyPort.PortMustBeZeroany port port must be zero.-
    400InvalidParameter.Name.MalformedThe specified Name is not valid.The specified name format is invalid. Enter the name in the valid format.
    400IncorrectStatus.ForwardEntryThe status of %s [%s] is incorrect.The DNAT entry to be deleted is in an invalid state.
    400OperationFailed.AnyPortConfigOperation failed because any port correspondence any protocol.-
    400Duplicated.DestinationPortThe specified param DestinationPort is duplicated.-
    400OperationUnsupported.EipInBindingCreate snat entry with eip in associating status is unsupported.You cannot use an associated EIP when you create an SNAT entry.
    400QuotaExceeded.ForwardEntrySessionManytoOneThe dnat session quota is exceed.The number of DNAT sessions exceeds the upper limit.
    400TaskConflictThe operation is too frequent, please wait a moment and try again.Your requests are too frequent. Try again later.
    400OperationFailed.DnatPortRangeLimitThe maximum number of port ranges that can be specified is exceeded.The maximum number of port ranges that can be specified is exceeded.
    404ResourceNotFound.NatIpThe specified resource of %s is not found.The specified NatIp parameter is not found.
    404InvalidRegionId.NotFoundThe specified RegionId does not exist in our records.The specified region ID does not exist.
    404InvalidForwardTableId.NotFoundSpecified forward table does not exist.The specified DNAT table does not exist. Check the parameter and try again.
    404InvalidExternalIp.NotFoundSpecified External Ip address does not found on the VRouterThe specified EIP does not exist.
    500System.ErrorERROR SYSTEM ERROR.-
    500InternalErrorThe request processing has failed due to some unknown error.An unknown error occurred.

    For a list of error codes, visit the Service error codes.

    Change history

    Change timeSummary of changesOperation
    2024-01-18API Description Update. The Error code has changedView Change Details
    2023-06-14The Error code has changedView Change Details
    2023-03-30The Error code has changedView Change Details
    2023-03-01The Error code has changedView Change Details