describe-vpn-connection missing information

[ankenyr]

Describe the issue

In the doc page I linked, the example json does not have tunnelOptions which looks to me to be a non-optional field that must always be present. It also seems that when updating things like the encryption algorithm, authentication algorithm, and diffie-helman groups the XML does not reflect those changes and is instead static.

Can the documentation be updated to clarify a couple of things

1. Are TunnelOptions always present or can the json sometimes not have them?
2. Is the XML intended to be authoritative or not?

Links

https://docs.aws.amazon.com/cli/latest/reference/ec2/describe-vpn-connections.html

[RyanFitzSimmonsAK]

Hi @ankenyr, thanks for reaching out and for your patience.

Are TunnelOptions always present or can the json sometimes not have them?

TunnelOptions should always appear in the response unless it's a very old VPN. Some old VPNs might be missing this field, and if that occurs, the service team can manually backfill it to fix that.

Is the XML intended to be authoritative or not?

A common nuance of AWS documentation is that when structures (such as TunnelOptions) are part of a response, the documentation will list every possible attribute of that structure in the Output section. However, not all operations return every attribute, and that does tend to confuse people. The examples section can clear that up, and typically you can take it as a source of truth, at least syntactically. In this case, this example was handwritten five years ago, so it makes sense that TunnelOptions would be absent.

I've reached out to the CLI example writer about addressing this. Thank you for bringing it to our attention!

Ticket # for internal use : P225675113

[ankenyr]

Just to be clear, there is XML in the JSON. My question was if the XML is to be considered authoritative because it is not. For example if you change the diffie helman groups or the encryption/authentication algorithms, it is not reflected in the XML but would be reflected in the JSON. The following is an example I created where I have removed sensitive values

{
 "VpnConnections": [
  {
   "Category": "VPN",
   "CustomerGatewayConfiguration": "<?xml version=\"1.0\" encoding=\"UTF-8\"?>\n<vpn_connection id=\"vpn-2345\">\n  <customer_gateway_id>cgw-1234</customer_gateway_id>\n  <vpn_gateway_id></vpn_gateway_id>\n  <vpn_connection_type>ipsec.1</vpn_connection_type>\n  <ipsec_tunnel>\n    <customer_gateway>\n      <tunnel_outside_address>\n        <ip_address>9.9.2.1</ip_address>\n      </tunnel_outside_address>\n      <tunnel_inside_address>\n        <ip_address>169.254.105.118</ip_address>\n        <network_mask>255.255.255.252</network_mask>\n        <network_cidr>30</network_cidr>\n      </tunnel_inside_address>\n      <bgp>\n        <asn>65000</asn>\n        <hold_time>30</hold_time>\n      </bgp>\n    </customer_gateway>\n    <vpn_gateway>\n      <tunnel_outside_address>\n        <ip_address>1.1.1.1</ip_address>\n      </tunnel_outside_address>\n      <tunnel_inside_address>\n        <ip_address>169.254.105.117</ip_address>\n        <network_mask>255.255.255.252</network_mask>\n        <network_cidr>30</network_cidr>\n      </tunnel_inside_address>\n      <bgp>\n        <asn>64512</asn>\n        <hold_time>30</hold_time>\n      </bgp>\n    </vpn_gateway>\n    <ike>\n      <authentication_protocol>sha1</authentication_protocol>\n      <encryption_protocol>aes-256-cbc</encryption_protocol>\n      <lifetime>28800</lifetime>\n      <perfect_forward_secrecy>group2</perfect_forward_secrecy>\n      <mode>main</mode>\n      <pre_shared_key>abcdefg</pre_shared_key>\n    </ike>\n    <ipsec>\n      <protocol>esp</protocol>\n      <authentication_protocol>hmac-sha1-96</authentication_protocol>\n      <encryption_protocol>aes-128-cbc</encryption_protocol>\n      <lifetime>3600</lifetime>\n      <perfect_forward_secrecy>group2</perfect_forward_secrecy>\n      <mode>tunnel</mode>\n      <clear_df_bit>true</clear_df_bit>\n      <fragmentation_before_encryption>true</fragmentation_before_encryption>\n      <tcp_mss_adjustment>1379</tcp_mss_adjustment>\n      <dead_peer_detection>\n        <interval>10</interval>\n        <retries>3</retries>\n      </dead_peer_detection>\n    </ipsec>\n  </ipsec_tunnel>\n  <ipsec_tunnel>\n    <customer_gateway>\n      <tunnel_outside_address>\n        <ip_address>9.9.2.1</ip_address>\n      </tunnel_outside_address>\n      <tunnel_inside_address>\n        <ip_address>169.254.133.230</ip_address>\n        <network_mask>255.255.255.252</network_mask>\n        <network_cidr>30</network_cidr>\n      </tunnel_inside_address>\n      <bgp>\n        <asn>65000</asn>\n        <hold_time>30</hold_time>\n      </bgp>\n    </customer_gateway>\n    <vpn_gateway>\n      <tunnel_outside_address>\n        <ip_address>54.71.105.202</ip_address>\n      </tunnel_outside_address>\n      <tunnel_inside_address>\n        <ip_address>169.254.133.229</ip_address>\n        <network_mask>255.255.255.252</network_mask>\n        <network_cidr>30</network_cidr>\n      </tunnel_inside_address>\n      <bgp>\n        <asn>64512</asn>\n        <hold_time>30</hold_time>\n      </bgp>\n    </vpn_gateway>\n    <ike>\n      <authentication_protocol>sha1</authentication_protocol>\n      <encryption_protocol>aes-128-cbc</encryption_protocol>\n      <lifetime>28800</lifetime>\n      <perfect_forward_secrecy>group2</perfect_forward_secrecy>\n      <mode>main</mode>\n      <pre_shared_key>hijklmnop</pre_shared_key>\n    </ike>\n    <ipsec>\n      <protocol>esp</protocol>\n      <authentication_protocol>hmac-sha1-96</authentication_protocol>\n      <encryption_protocol>aes-128-cbc</encryption_protocol>\n      <lifetime>3600</lifetime>\n      <perfect_forward_secrecy>group2</perfect_forward_secrecy>\n      <mode>tunnel</mode>\n      <clear_df_bit>true</clear_df_bit>\n      <fragmentation_before_encryption>true</fragmentation_before_encryption>\n      <tcp_mss_adjustment>1379</tcp_mss_adjustment>\n      <dead_peer_detection>\n        <interval>10</interval>\n        <retries>3</retries>\n      </dead_peer_detection>\n    </ipsec>\n  </ipsec_tunnel>\n</vpn_connection>\n",
   "CustomerGatewayId": "cgw-1234",
   "GatewayAssociationState": "associated",
   "Options": {
    "EnableAcceleration": false,
    "LocalIpv4NetworkCidr": "0.0.0.0/0",
    "OutsideIpAddressType": "PublicIpv4",
    "RemoteIpv4NetworkCidr": "0.0.0.0/0",
    "StaticRoutesOnly": false,
    "TunnelInsideIpVersion": "ipv4",
    "TunnelOptions": [
     {
      "DpdTimeoutAction": "clear",
      "EnableTunnelLifecycleControl": false,
      "IkeVersions": [
       {
        "Value": "ikev1"
       },
       {
        "Value": "ikev2"
       }
      ],
      "LogOptions": {
       "CloudWatchLogOptions": {
        "LogEnabled": false,
        "LogGroupArn": "",
        "LogOutputFormat": "json"
       }
      },
      "OutsideIpAddress": "1.1.1.1",
      "Phase1DHGroupNumbers": [
       {
        "Value": 2
       },
       {
        "Value": 20
       },
       {
        "Value": 21
       },
       {
        "Value": 22
       },
       {
        "Value": 23
       },
       {
        "Value": 24
       }
      ],
      "Phase1EncryptionAlgorithms": [
       {
        "Value": "AES256"
       },
       {
        "Value": "AES128-GCM-16"
       }
      ],
      "Phase1IntegrityAlgorithms": [
       {
        "Value": "SHA1"
       },
       {
        "Value": "SHA2-512"
       }
      ],
      "Phase2DHGroupNumbers": [
       {
        "Value": 14
       },
       {
        "Value": 15
       },
       {
        "Value": 16
       },
       {
        "Value": 20
       },
       {
        "Value": 21
       },
       {
        "Value": 22
       },
       {
        "Value": 23
       },
       {
        "Value": 24
       }
      ],
      "Phase2EncryptionAlgorithms": [
       {
        "Value": "AES128"
       },
       {
        "Value": "AES128-GCM-16"
       }
      ],
      "Phase2IntegrityAlgorithms": [
       {
        "Value": "SHA2-512"
       }
      ],
      "PreSharedKey": "abcdefg",
      "StartupAction": "add",
      "TunnelInsideCidr": "169.254.105.116/30"
     },
     {
      "EnableTunnelLifecycleControl": false,
      "LogOptions": {
       "CloudWatchLogOptions": {
        "LogEnabled": false
       }
      },
      "OutsideIpAddress": "54.71.105.202",
      "PreSharedKey": "hijklmnop",
      "TunnelInsideCidr": "169.254.133.228/30"
     }
    ]
   },
   "Routes": [],
   "State": "modifying",
   "Tags": [
    {
     "Key": "Name",
     "Value": "foo2"
    }
   ],
   "TransitGatewayId": "tgw-5678",
   "Type": "ipsec.1",
   "VgwTelemetry": [
    {
     "AcceptedRouteCount": 0,
     "LastStatusChange": "2024-12-12 22:12:34+00:00",
     "OutsideIpAddress": "1.1.1.1",
     "Status": "DOWN",
     "StatusMessage": "IPSEC IS DOWN"
    },
    {
     "AcceptedRouteCount": 0,
     "LastStatusChange": "2024-12-12 22:12:34+00:00",
     "OutsideIpAddress": "54.71.105.202",
     "Status": "DOWN",
     "StatusMessage": "IPSEC IS DOWN"
    }
   ],
   "VpnConnectionId": "vpn-2345"
  }
 ]
}

You can see I have changed Phase2DHGroupNumbers to be a certain number of explicit values. However in the XML you can see it is only group2.

What should the XML be used for if it is not accurate? For older VPNs that do not have tunneloptions, how should someone get the correct configuration of the VPN?

[RyanFitzSimmonsAK]

For example if you change the diffie helman groups or the encryption/authentication algorithms, it is not reflected in the XML but would be reflected in the JSON.

I'm not sure I'm following here. The XML you're referring to (CustomerGatewayConfiguration) doesn't contain the same attributes as the JSON. Unless you were referring to the JSON response of DescribeCustomerGateways? For the XML to change, you'd need to change an attribute of your customer gateway.

For older VPNs that do not have tunneloptions, how should someone get the correct configuration of the VPN?

Using modify-vpn-tunnel-options should backfill the TunnelOption value automatically.

[ankenyr]

Yea the CustomerGatewayConfiguration does not contain the correct information. In the above I setup my tunnels and the correct configuration is reflected in the JSON. The xml in CustomerGatewayConfiguration does not have the correct configuration information. The documentation says

The configuration information for the VPN connection’s customer gateway
This is not correct though as it would be incompatible. The AWS side has Phase2DHGroupNumbers configured to exclude value 2 which would map to group2 in the xml. The XML however has <perfect_forward_secrecy>group2</perfect_forward_secrecy>

Is CustomerGatewayConfiguration supposed to be accurate to the actual configuration? If so, that is not reflected in the real world and there is a bug.
If it is not supposed to be accurate then the documentation needs to be updated stating as such and it should be clarified what it is used for. My suspicion is that it is only used by AWS to create the configs generated by the "download configuration " button