backends.diameter

Diameter backend

The diameter backend forwards existing Diameter requests or sends named RADIUS-to-Diameter bridge queries or explicitly constructed application requests through a Diameter server, peer group, and local node.

When a peer answers with DIAMETER_UNABLE_TO_DELIVER (3002) or DIAMETER_TOO_BUSY (3004), the backend sends the request once more to another eligible member of the peer group that has not received it, as RFC 6733 section 7.1.3 recommends for 3004. The retry keeps the End-to-End ID and is not marked as a retransmission. A query or bridge retry increments the backend's Retries counter. Without another eligible member, with selection no_fallback, or when the backend timeout has passed, the first answer is used. When the server's maximum_pending_transactions limit is full, the request fails at once without trying other members, and the backend's PoolExhausted counter increments.

Forwarding an existing request

Set action proxy; and call the backend without a query name from a Diameter handler:

backends {
    diameter "UPSTREAM" {
        server "DIAMETER";
        local_node "PROXY";
        peer_group "UPSTREAM";
        action proxy;
    }
}

aaa {
    policy "DIAMETER_POLICY" {
        handler "NASREQ" {
            conditions all {
                diameter.destination_realm == "example.net";
                diameter.application_id == diameter.APPLICATION_NASREQ;
                diameter.command_code == diameter.COMMAND_AA;
            }
            @execute {
                backend "UPSTREAM";
            }
        }
        handler "UNHANDLED" {
            @execute { reject; }
        }
    }
}

Select DIAMETER_POLICY with the Diameter server's policy statement. Handler conditions select which requests are forwarded. The inbound server and local node must match the backend's server and local_node.

The backend preserves Session-Id, End-to-End ID, application AVPs, and upstream Proxy-Info. It assigns a new Hop-by-Hop ID for the outgoing connection, adds its own Proxy-Info, and removes that group from the correlated return answer. Peer selection excludes the incoming connection and peers already in Route-Record. When the request's Destination-Host is a member of the peer group, that member is preferred; otherwise the request goes to the group's other members in their configured order, which relay it towards the Destination-Host. If the selected peer fails, the request is retransmitted to the next eligible member. An unavailable next hop or a full pending transaction limit returns DIAMETER_UNABLE_TO_DELIVER (3002); a forwarding loop returns DIAMETER_LOOP_DETECTED (3005). A request that fails validation, for example with an unknown mandatory AVP, is answered with the RFC 6733 Result-Code for the failure and the offending AVP as Failed-AVP.

The answer is sent after policy completion. Final actions can inspect diameter.answer.* and diameter.result_code. Forwarded answer AVPs and Result-Code are immutable. A later policy rejection or error replaces an upstream success with a local rejection or error. Ignore and discard results send no answer.

Remote EAP State is forwarded unchanged; the proxy creates no local challenge state. Locally issued EAP tokens cannot be forwarded. Backend action timeout sets a single deadline across forwarding attempts; the default is 30s.

Constructing a request

Use application_id, command_code and bindings to originate a Diameter request from any parent context, including HTTP. These statements replace the bridge query's profile and destination_realm statements:

query "PAP" {
    application_id diameter.APPLICATION_NASREQ;
    command_code diameter.COMMAND_AA;
    bindings {
        diameter.request.Session-Id = http.request.session_id;
        diameter.request.Destination-Realm = "example.net";
        diameter.request.Auth-Application-Id = diameter.APPLICATION_NASREQ;
        diameter.request.Auth-Request-Type = "AUTHORIZE_AUTHENTICATE";
        diameter.request.User-Name = http.request.username;
        diameter.request.User-Password = http.request.password;
    }
    mapping {
        http.response.result_code = diameter.result_code;
        http.response.reply_message = diameter.answer.Reply-Message;
    }
}

Invoke the query with backend { name "UPSTREAM"; query "PAP"; }. Bindings read from the parent context and modify an isolated outgoing request. The dictionary validates AVP types, and the application schema validates the complete request before transmission. AVP bindings support replacement (=), append (+=) and insert unless present (?=). Grouped AVPs require a typed application action and cannot be constructed through these bindings.

Origin-Host and Origin-Realm come from the configured local node. The runtime owns request identifiers, proxy metadata and Result-Code. Request bindings cannot replace these fields. Incoming Diameter request fields remain read-only in ordinary policy actions.

Answer mappings read the correlated answer and write to the parent context. diameter.answer.AVP returns a list; diameter.result_code returns a scalar. The target namespace determines how mapped values are stored. An HTTP field accepts one AVP as a scalar and an empty list as JSON null. Multiple AVPs require a target that accepts value lists, such as vars or RADIUS attributes. OctetString AVPs remain bytes and serialize as hexadecimal strings in HTTP JSON. Mappings run for success and rejection answers, including empty AVP lists. Result-Code 1001 or 2xxx returns backend acceptance, 4xxx returns rejection, and other result classes return an error after mapping the answer. Backend timeout applies across peer selection, sending and waiting; the default is 30s. Transport-control commands cannot be originated through this query.

Named bridge queries

Each named query selects a profile and destination realm. Available profiles are nasreq, diameter_eap, nasreq_accounting, and r4_base_accounting. Bridge profile values accept both underscore and hyphen spellings. Prefer underscores, such as diameter_eap. These queries require a RADIUS parent context. The accounting failure policy and session termination option apply only to accounting profiles.

For nasreq, select the operation with auth_request_type:

Successful queries still return the normal RADIUS Access-Accept outcome. Other bridge profiles and explicitly constructed queries reject this option. Constructed queries assign "AUTHENTICATE_ONLY", "AUTHORIZE_ONLY", or "AUTHORIZE_AUTHENTICATE" to Auth-Request-Type. Policy comparisons use the diameter.AUTH_REQUEST_TYPE_* constants. Challenge continuations retain both the original operation and destination; another operation cannot reuse an existing RADIUS State token.

Backend action timeout sets one deadline for a bridge query: it covers peer selection, the bridged request, and, for an accounting STOP with send_str_on_stop, the Session-Termination-Request that follows. The default is 30s.

Each bridged session has its own Diameter Session-Id that starts with the local node identity and continues with a random value. An accounting START draws a new random Session-Id that the session's INTERIM and STOP records reuse. Records that arrive without a known START, for example after a restart, use a Session-Id derived from a random value chosen when Radiator Server starts.

Challenge continuations, accounting records that carry the bridge's Class, and session termination name the server that answered the authorization in Destination-Host and prefer the peer that relayed that answer. When that peer is unavailable, the request goes to the group's other members, which relay it towards the Destination-Host.

With accounting_failure_policy acknowledge, a record that cannot be delivered is still acknowledged to the NAS and the failure is logged. Use retry when the NAS must resend undelivered records.

The NAS originates START, INTERIM and STOP accounting records. A bridge query translates received records; successful authentication does not automatically create accounting records or schedule periodic INTERIM updates.

Accounting bridges preserve opaque Class values in both directions. RADIUS retransmissions that change only the identifier, authenticator, attribute order, or Acct-Delay-Time retain their Diameter accounting record identity.

After a STOP completes, matching RADIUS retransmissions receive an acknowledgment without another accounting or session termination request. Completion records expire after 5 minutes without a matching accounting request. They share the 65,536-entry accounting session limit; capacity pressure evicts the oldest completed entry before rejecting a new active session. Replay suppression ends when a completion record expires or is evicted.

A backend may enable direct forwarding and define named bridge queries. Calls with a query name use that query; calls without one require action proxy;.

See the Diameter server configuration for local nodes, peers, and server policies.