All Products
Search

This Product

    NAT Gateway:CreateForwardEntry

    Document Center

    NAT Gateway:CreateForwardEntry

    Last Updated:Aug 28, 2026

    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.

    Try it now

    Try this API in OpenAPI Explorer, no manual signing needed. Successful calls auto-generate SDK code matching your parameters. Download it with built-in credential security for local usage.

    Test

    RAM authorization

    No authorization for this operation. If you encounter issues with this operation, contact technical support.

    Request parameters

    Parameter

    Type

    Required

    Description

    Example
    RegionId

    string

    Yes

    The region ID of the NAT gateway.

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

    cn-hangzhou
    ForwardTableId

    string

    Yes

    The ID of the DNAT table.

    ftb-bp1mbjubq34hlcqpa****
    ExternalIp

    string

    Yes

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

    string

    Yes

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

    string

    Yes

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

    string

    Yes

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

    string

    Yes

    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
    ForwardEntryName

    string

    No

    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
    ClientToken

    string

    No

    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****
    PortBreak

    boolean

    No

    Whether to enable port breakthrough, with values:

    • true: Enable port breakthrough.

    • false (default): Do not enable port breakthrough.

    Note

    When both DNAT and SNAT entries use the same public IP address, if you need to configure a port number greater than 1024, you must set PortBreak to true.

    false
    DryRun

    boolean

    No

    Indicates whether to perform a dry run of the request. Values:

    • true: Sends a check request without creating a DNAT entry. The checks include whether the AccessKey is valid, the RAM user's authorization status, and if all required parameters are filled out. If any check fails, the corresponding error is returned. If all checks pass, an error code DryRunOperation is returned.

    • false (default): Sends a normal request. After passing the checks, it returns a 2xx HTTP status code and creates a DNAT entry.

    false

    Response elements

    Element

    Type

    Description

    Example

    object

    ForwardEntryId

    string

    The ID of the DNAT entry.

    fwd-119smw5tkasdf****
    RequestId

    string

    The request ID.

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

    Examples

    Success response

    JSON format

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

    Error codes

    HTTP status code

    Error code

    Error message

    Description
    400 UnsupportedFeature.PrivateLinkEnabled The feature of PrivateLinkEnabled is not supported.
    400 UnsupportedFeature.PortSegment The feature of PortSegment is not supported.
    400 ExclusiveParam.%sAnd%s The param of %s and %s are mutually exclusive. You cannot specify %s and %s at the same time.
    400 DuplicatedParam.InternalPort The param of %s is duplicated. Duplicate or occupied InternalPort parameter
    400 DuplicatedParam.ExternalPort The param of %s is duplicated. The DNAT public network port has been used repeatedly.
    400 OperationFailed.AnyPortConfig Operation failed because any port correspondence any protocol The operation failed. There is a conflict with another entry, any port or any protocol type.
    400 OperationUnsupported.ForwardEntry Duplicated destination ip port is unsupported. You cannot specify duplicate destination IP addresses or destination ports.
    400 InvalidIp.NotInNatgw The specified Ip not belong to natgateway.
    400 QuotaExceeded.ForwardEntry The quota of %s is exceeded, usage %s/%s.
    400 IncorrectStatus.NatIp The status of %s [%s] is incorrect. The status of NatIp is incorrect.
    400 Forbidden.IpHasBeenUsedInSnat The source ip can't be used. Because it has been used in snat.
    400 InvalidExternalIp.Malformed The specified ExternalIp is not a valid IP address.
    400 InvalidInternalIp.Malformed The specified InternalIp is not a valid IP address.
    400 InvalidExternalPort.Malformed The specified ExternalPort is not a valid port.
    400 InvalidInternalPort.Malformed The specified InternalPort is not a valid port.
    400 Forbidden.DestnationIpOutOfVpcCIDR The specified Internal Ip is Out of VPC CIDR.
    400 Forbidden.DestinationIpOutOfVswitchCIDR The specified Internal Ip is Out of VSwitch CIDR.
    400 InvalidProtocal.ValueNotSupported The specified IpProtocol does not support.
    400 IncorretForwardEntryStatus Some Forward entry status blocked this operation..
    400 ForwardEntry.Duplicated The specified ExternalIp, IpProtocol, ExternalPort,InternalIp, InternalPort is duplicated
    400 Forbidden.ExternalIp.UsedInSnatTable The specified ExternalIp is already used in SnatTable
    400 Forbindden The specified Instance already bind eip
    400 Forbidden.InternalIpOutOfVpcCIDR The specified Internal Ip is Out of VPC CIDR.
    400 Invalid.natgwNotExist The specified natgateway not exist.
    400 MissingParameter Missing mandatory parameter
    400 AnyPort.PortMustBeZero any port port must be zero.
    400 InvalidParameter.Name.Malformed The specified Name is not valid.
    400 IncorrectStatus.ForwardEntry The status of %s [%s] is incorrect. The DNAT entry to be deleted is in an invalid state.
    400 Duplicated.DestinationPort The specified param DestinationPort is duplicated.
    400 OperationUnsupported.EipInBinding Create snat entry with eip in associating status is unsupported. You cannot use an associated EIP when you create an SNAT entry.
    400 QuotaExceeded.ForwardEntrySessionManytoOne The dnat session quota is exceed. The number of DNAT sessions exceeds the upper limit.
    400 TaskConflict The operation is too frequent, please wait a moment and try again. Your requests are too frequent. Try again later.
    400 OperationFailed.DnatPortRangeLimit The maximum number of port ranges that can be specified is exceeded. The maximum number of port ranges that can be specified is exceeded.
    400 IncorrectStatus.NATGW NATGW status is invalid. The NAT gateway is in an invalid state.
    400 OperationFailed.ForwardEntryNotAllowSrcIpEqualDstIp The source IP of forward entry is not allowed to equal destination IP. The public IP address of the DNAT entry is not allowed to be equal to the private IP address.
    500 System.Error ERROR SYSTEM ERROR.
    500 InternalError The request processing has failed due to some unknown error.
    404 ResourceNotFound.NatIp The specified resource of %s is not found.
    404 InvalidRegionId.NotFound The specified RegionId does not exist in our records.
    404 InvalidForwardTableId.NotFound Specified forward table does not exist.
    404 InvalidExternalIp.NotFound Specified External Ip address does not found on the VRouter

    See Error Codes for a complete list.

    Release notes

    See Release Notes for a complete list.