Siteminder Access Gateway 12.9 Release Proxy Engine HttpClient 5.x settings guide
Article ID: 421739
Updated On:
Products
Issue/Introduction
Per 12.9 Release Note Changes , Access Gateway now supports HttpClient 5.x to communicate with a backend server.
Access Gateway uses HttpClient to send requests to and receive responses from the backend server.
With this upgrade, there were changes to the httpClient settings within the server.conf from earlier releases that you should be aware of when upgrading.
This KB also highlights the connection lifecycle through the HttpClient 5.x.
Environment
Siteminder Access Gateway 12.9 and onward releases
Resolution
###### Http Client 5.x (in 12.9) settings ######
- changes to the httpclient 5.x described here Changes due to HttpClient5.x
it mentions the following
The following parameters are no longer configurable in the server.conf file as they are no longer supported by HttpClient:
http_connection_pool_min_size
http_connection_pool_incremental_factor
http_connection_pool_max_attempts
The http_connection_stalecheck parameter is no longer configurable in the server.conf file as its configuration handled using the http_connection_pool_connection_timeout.
###### Recommendations After Upgrade ######
It is recommended that you review the server.conf after upgrading to 12.9 or newer release and remove any parameter that is no longer supported and verify the configuration of the new
parameters. The below shows an example of Active parameters, these parameters are configured per environment basis, please adjust it to meet your environment requirements to note that the "http_connection_pool_wait_timeout" defaults to 0 out of the box with 12.9 GA release and should be adjusted to 60000 (please see detailed explanation below for this parameter)
# ACTIVE PARAMETERS
http_connection_pool_max_size="700" #Max limit
http_connection_pool_connection_timeout="1 minute" #Idle Timeout
http_connection_pool_wait_timeout="60000" --> needs to be Adjusted from 0
http_connection_timeout="15 minutes" #Connection creation timeout
http_socket_timeout="900000" #Socket read/write timeout
<connection-pool name="connection oriented authentication">
connection-timeout="10 seconds" #NTLM/Kerberos idle timeout
max-size="200"
wait-timeout="60000" # Can be added if being used
enabled="yes"
</connection-pool>
# REMOVED (deprecated/ignored):
# http_connection_pool_min_size="2"
# http_connection_pool_incremental_factor="2"
# http_connection_pool_max_attempts="3"
# http_connection_stalecheck="true"
Defines the time, in milliseconds, that Access Gateway waits for an available connection. The default, 0, specifies that Access Gateway
waits for a connection until notified and invalidates the use of http_connection_pool_max_attempts.
Example
│ REQUEST ARRIVES
│ ↓
│ Need Connection
│ ↓
│ ┌────────────────────────
│ │ http_connection_pool_wait_timeout (0 → 60000)
│ │ "How long to WAIT for a connection?"
│ │
│ │ If connection not immediately available:
│ │ - Creating new one: Wait 50-300ms ⏱
│ │ - All busy: Wait for one to free up ⏱
│ └────────────────────────
http_keepalive_time
The parameter http_keepalive_time is set as maximum TimeToLive (TTL) in the connection configuration. Forces reconnection after X minutes regardless of usage. Default: 3 minutes - connections are closed after 3 minutes regardless of idle/active state.
http_connection_pool_inactive_connection_validate_interval
The parameter http_connection_pool_inactive_connection_validate_interval sets the validation interval for inactive connections before reusing them. If a connection has been idle longer than this interval, it will be validated before use. Checks if connection is still alive (not closed by server). Default: -1 (disabled) - No validation, connections are reused without checking. If enabled (e.g., 2000ms): Connections idle for > 2 seconds are validated before reuse. It prevents "stale connection" errors (server closed connection, but client doesn't know), but adds small overhead (validation check) but prevents failed requests on dead connections. Useful when backend servers have aggressive connection timeout policies.
###### HttpClient 5.x connection pool Q&A ######
NOTE: the Explanation below is based on the example configuration in the previous section.
**** 1. What is the minimum connections maintained in pool?
Answer: ZERO (0)
The configuration maintains NO minimum connections. The pool can completely empty to 0 connections.
http_connection_pool_min_size="2" # ❌ IGNORED (deprecated)
This parameter is deprecated and completely ignored by Apache HttpClient 5.x.
**** 2. What happens when idle timeout reaches and connection closes? This is based on http_connection_pool_connection_timeout
Answer: Nothing - the pool just shrinks. No replacement.
Connection becomes idle ↓Wait 1 minute ↓Close connection ↓Pool size decreases (e.g., 50 → 49) ↓❌ NO automatic replacement created ↓Pool just stays at 49 until new request arrives
The pool is purely reactive, not proactive.
**** 3. Does it open new connections or only when load comes in?
Answer: ONLY when load comes in (on-demand only)The pool does NOT proactively create connections. It only creates them when:
- A request arrives AND
- No idle connection available AND
- Pool size < max (700)
┌─────────────────────
│ When Pool Creates Connections │
├──────────────────────
│ ✓ YES - When request arrives and needs one
│ ❌ NO - When connection closes
│ ❌ NO - When pool becomes empty
│ ❌ NO - To maintain minimum
│ ❌ NO - To anticipate load
│ ❌ NO - To "warm up" the pool
```
┌────────────────────
│ Connection Lifecycle with Both Timeouts │
├──────────────────────────
│
│ REQUEST ARRIVES
│ ↓
│ Need Connection
│ ↓
│ ┌────────────────────────
│ │ http_connection_pool_wait_timeout (0 → 60000)
│ │ "How long to WAIT for a connection?"
│ │
│ │ If connection not immediately available:
│ │ - Creating new one: Wait 50-300ms ⏱
│ │ - All busy: Wait for one to free up ⏱
│ └────────────────────────
│ ↓
│ Got Connection, Use It
│ ↓
│ Send Request, Get Response
│ ↓
│ Request Complete, Return Connection to Pool
│ ↓
│ ┌─────────────────────────
│ │ http_connection_pool_connection_timeout (1 minute)
│ │ "How long to KEEP idle connection?"
│ │
│ │ Connection sits idle in pool:
│ │ - If reused within 1 min: Keep alive ✓
│ │ - If idle for 1 min: Close & remove ✗
│ └─────────────────────
│ ↓
│ Either: Reused by next request OR Closed after 1 min
│
Complete Pool Lifecycle Example
Morning After Quiet Night
00:00 AM (Midnight)
Pool: 0 connections (all closed overnight)
08:00 AM - First request of the day arrives
Pool: 0/700 connections
Action: Create connection 1 (takes 100ms)
↓
With wait_timeout=0: ❌ FAILS (can't wait 100ms)
With wait_timeout=60000: ✓ Waits 100ms, succeeds
08:01 AM - More requests arrive
Pool: 1 connection (from first request)
Action: Create more connections as needed
09:00 AM - Business hours
Pool: 150 connections (grew on-demand)
18:00 PM - Traffic decreases
Pool: 150 connections (many become idle)
Idle connections start timing out (1 minute each)
Pool slowly shrinks: 150 → 140 → 130 → 120...
23:00 PM - Very low traffic
Pool: 10 connections (mostly idle)
Still shrinking...
00:00 AM (Next day)
Pool: 0 connections (back to empty)
Cycle repeats
Cold Start Problem
Pool at 0 (overnight) ↓First morning request arrives ↓Must create connection (100ms) ↓wait_timeout=0 → Can't wait even 100ms ↓❌ FAILS: "Timeout deadline: 0 MILLISECONDS"
This happens:
Every morning (pool at 0 after night)
After any quiet period (pool shrinks to 0)
During connection churn (idle timeouts)
No Minimum = Dynamic Efficiency
Benefits:
✓ Saves resources during low traffic
✓ Automatically adapts to load
✓ No wasted connections
Trade-offs:
✗ "Cold start" delay (first requests must wait for connection creation)
✗ Requires wait_timeout > 0 to handle this gracefully
Connection Closes = Pool Just Shrinks
50 connections → Idle timeout closes 1 → 49 connections
NO automatic replacement!Pool just stays at 49 until next request creates one.
Only On-Demand Creation
Pool completely empty (0 connections)
↓
Stays at 0 forever
↓
UNTIL
↓
Request arrives
↓
Then creates connection (50-300ms)
Pool completely empty (0 connections) ↓Stays at 0 forever ↓UNTIL ↓Request arrives ↓Then creates connection (50-300ms)
Bottom line:
- Minimum = 0 (no minimum maintained)
- Closes = no replacement (just shrinks)
- Creates = only on-demand when requests arrive
**** 4. (From Release 12.9) http_connection_retry_waittime , how does this work ?
Defines the time in milliseconds that Access Gateway waits between two connection retries when an I/O exception occurs. To use this parameter, manually add it in the server.conf file and set a value between 100 - 1000.
http_connection_retry_waittime controls the delay between automatic retry attempts when a request fails due to recoverable errors like connection resets or timeouts.
| Default Value | 100 milliseconds |
| Max Value | 1000 milliseconds (enforced) |
| Purpose | Wait time between retry attempts |
| Related Parameter | http_connection_retry_count (default: 3) |
| Applies To | Backend I/O errors (SocketException, etc.) |
| Does NOT Apply To | Your current ConnectionRequestTimeoutException |
This is applicale for Retry-able Errors (Automatic Retry)
- SocketException - Connection reset, broken pipe
- NoHttpResponseException - Server closed connection
- ConnectException - Connection refused
- SocketTimeoutException - Read/write timeout
- Some SSL exceptions
Retry Flow Example
ATTEMPT 1: Send request
↓
SocketException (connection reset)
↓
⏱ Wait 100ms (retry_waittime)
↓
ATTEMPT 2: Retry with new connection
↓
SocketException (connection reset again)
↓
⏱ Wait 100ms
↓
ATTEMPT 3: Retry with new connection
↓
✓ SUCCESS
Total time: ~300ms (3 attempts + 2×100ms waits)
###### HttpClient 5.x behavior ######
────────────────────────────────────────────────────────────┐
│ Connection Pool Behavior (Apache HttpClient 5.x)
├────────────────────────────────────────────────────────────┤
│ STARTUP
│ ──────────────────────────────────────────────────────────│
│ Pool starts with: 0 connections
│ Minimum maintained: 0 connections
│ FIRST REQUESTS ARRIVE (Cold Start)
│ ──────────────────────────────────────────────────────────│
│ T=0ms: Request 1 arrives
│ Pool: 0/700 connections
│ Action: Create connection 1 (50-300ms)
│
│ T=10ms: Request 2 arrives (while #1 creating)
│ Pool: 0/700 (1 pending)
│ Action: Create connection 2 (50-300ms)
│
│ T=20ms: Request 3 arrives (while #1,#2 creating)
│ Pool: 0/700 (2 pending)
│ Action: Create connection 3 (50-300ms)
│
│ T=100ms: Connections 1,2,3 ready
│ Pool: 3/700 connections (all in use)
│
│ STEADY STATE (Active Traffic)
│ ──────────────────────────────────────────────────────────│
│ Pool grows to: 50 connections (example)
│ Status:
│ - 30 connections IN USE
│ - 20 connections IDLE (available)
│ IDLE TIMEOUT (Connection Closes After 1 Minute)
│ ──────────────────────────────────────────────────────────│
│ T=0: Connection 1 finishes, returned to pool (IDLE)
│ Pool: 50 total (30 in use, 20 idle)
│
│ T=60s: Connection 1 idle for 1 minute
│ Action: Close connection 1
│ Pool: 49 total (30 in use, 19 idle)
│ Replacement: NONE (no automatic replacement)
│
│ T=120s: Connection 2 idle for 1 minute
│ Action: Close connection 2
│ Pool: 48 total (30 in use, 18 idle)
│ Replacement: NONE
│
│ This continues...
│
│ NO TRAFFIC (All Connections Become Idle)
│ ─────────────────────────────────────────────────────────│
│ T=0: Last request completes
│ Pool: 50 total (all idle)
│
│ T=1min: Connection 1 closes (idle timeout)
│ Pool: 49 total (all idle)
│
│ T=2min: Connection 2 closes (idle timeout)
│ Pool: 48 total (all idle)
│
│ ... (continues until all close) ...
│
│ T=50min: Last connection closes
│ Pool: 0/700 connections
│ ↓
│ BACK TO STARTUP STATE
│
│ NEXT REQUEST (After Period of No Traffic)
│ ──────────────────────────────────────────────────────────│
│ Request arrives
│ Pool: 0/700 connections
│ Action: Create connection 1 (starts from scratch)
└────────────────────────────────────────────────────────────┘
Key Behaviors
### 1. No Minimum Maintained
┌─────────────────────────────────────────────┐
│ Pool Size Over Time (No Traffic)
├─────────────────────────────────────────────┤
│
│ 50 connections ─
│ │ Idle timeout (1 min each) │
│ 40 connections │ closes connections│
│ │ one by one│
│ 30 connections │
│ 20 connections │
│ 10 connections │
│ 0 connections ─┘
│ ↑
│ Pool empties completely │
│ NO minimum maintained│
└─────────────────────────────────────────────┘
**Why no minimum?**
- 'min_size' parameter is deprecated and ignored
- Apache HttpClient 5.x doesn't support pre-creation
- Pool is purely on-demand
### 2. Idle Timeout Behavior
**When connection becomes idle:**
Connection finishes request
↓
Returned to pool (status: AVAILABLE)
↓
Timer starts: 1 minute countdown
↓
┌────────────────────────────────────────────┐
│ If reused within 1 minute:
│ ✓ Timer resets
│ ✓ Connection stays in pool
│ ✓ Pool size unchanged
└────────────────────────────────────────────┘
OR
┌────────────────────────────────────────────┐
│ If NOT reused for 1 minute:
│ ✗ Connection closes
│ ✗ Removed from pool
│ ✗ Pool size decreases
│ ❌ NO replacement created
└────────────────────────────────────────────┘
**Important:** No automatic replacement - pool just shrinks!
### 3. On-Demand Creation Only
┌──────────────────────────────────────────────────┐
│ When Does Pool Create New Connections? │
├──────────────────────────────────────────────────┤
│ ✓ YES - Creates when:
│ • Request arrives
│ • No idle connection available
│ • Pool size < max_size (700)
│
│ ❌ NO - Does NOT create when:
│ • Connection closes due to idle timeout
│ • Pool shrinks below any threshold
│ • Pool becomes empty
│ • Anticipating future load
│ • "Warming up" the pool
│
│ Result: Purely reactive, not proactive
└──────────────────────────────────────────────────┘
Feedback
