Loading...
Searching...
No Matches
RTR connection manager

## Data Structures

struct | rtr_mgr_group

## Typedefs

typedef void(* | rtr_mgr_status_fp) (const struct rtr_mgr_group *, enum rtr_mgr_status, const struct rtr_socket *, void *)

## Enumerations

enum | rtr_mgr_status { RTR_MGR_CLOSED , RTR_MGR_CONNECTING , RTR_MGR_ESTABLISHED , RTR_MGR_ERROR }

## Functions

int | rtr_mgr_add_group (struct rtr_mgr_config *config, const struct rtr_mgr_group *group)
bool | rtr_mgr_conf_in_sync (struct rtr_mgr_config *config)
int | rtr_mgr_for_each_group (struct rtr_mgr_config *config, void(*fp)(const struct rtr_mgr_group *group, void *data), void *data)
void | rtr_mgr_for_each_ipv4_record (struct rtr_mgr_config *config, pfx_for_each_fp fp, void *data)
void | rtr_mgr_for_each_ipv6_record (struct rtr_mgr_config *config, pfx_for_each_fp fp, void *data)
void | rtr_mgr_free (struct rtr_mgr_config *config)
struct rtr_mgr_group * | rtr_mgr_get_first_group (struct rtr_mgr_config *config)
int | rtr_mgr_get_spki (struct rtr_mgr_config *config, const uint32_t asn, uint8_t *ski, struct spki_record **result, unsigned int *result_count)
int | rtr_mgr_init (struct rtr_mgr_config **config_out, struct rtr_mgr_group groups[], const unsigned int groups_len, const unsigned int refresh_interval, const unsigned int expire_interval, const unsigned int retry_interval, const pfx_update_fp update_fp, const spki_update_fp spki_update_fp, const rtr_mgr_status_fp status_fp, void *status_fp_data)
int | rtr_mgr_remove_group (struct rtr_mgr_config *config, unsigned int preference)
int | rtr_mgr_start (struct rtr_mgr_config *config)
const char * | rtr_mgr_status_to_str (enum rtr_mgr_status status)
void | rtr_mgr_stop (struct rtr_mgr_config *config)
int | rtr_mgr_validate (struct rtr_mgr_config *config, const uint32_t asn, const struct lrtr_ip_addr *prefix, const uint8_t mask_len, enum pfxv_state *result)

## Detailed Description

The RTR connection manager is initialized with one or multiple groups of rtr_sockets. Each group is configured with a preference value and contains a set of rtr_socket RTR sockets. It connects to all sockets of the group with the lowest preference value.
In case of failures, the connection manager establishes connections to RTR servers of another group with the next lowest preference value (see IETF RFC 6810 for details about error handling).
RTRlib also supports a Retry Interval (see draft-ietf-sidr-rpki-rtr-rfc6810-bis). If a more preferred group is online again, the RTR connection manager will switch back and close connections to the caches of the less preferred group.

## Enumeration Type Documentation

## rtr_mgr_status

enum rtr_mgr_status

Status of a rtr_mgr_group.

Enumerator
RTR_MGR_CLOSED | RTR sockets are disconnected
RTR_MGR_CONNECTING | RTR sockets trying to establish a connection.
RTR_MGR_ESTABLISHED | All RTR sockets of the group are synchronized with rtr servers.
RTR_MGR_ERROR | Error occurred on at least one RTR socket.

## Function Documentation

## rtr_mgr_add_group()

int rtr_mgr_add_group | ( | struct rtr_mgr_config * | config,
|  | const struct rtr_mgr_group * | group )

Adds a new rtr_mgr_group to the linked list of a initialized config.

A new group must have at least one rtr_socket associated with it. This socket must have at least one initialized transport socket associated with it. The new group must have a preference value that is none of the already present groups have. More than one rtr_mgr_group with the same preference is not allowed.

Parameters

  config | A rtr_mgr_config struct that has been initialized previously with rtr_mgr_init
  group | A rtr_mgr_group with at least one rtr_socket and a preference value that no existing group has.

Returns
  RTR_INVALID_PARAM If a group with the same preference value already exists.
  RTR_ERROR If an error occurred while adding the group.
  RTR_SUCCESS If the group was successfully added.

## rtr_mgr_conf_in_sync()

bool rtr_mgr_conf_in_sync | ( | struct rtr_mgr_config * | config | ) |

Check if rtr_mgr_group is fully synchronized with at least one group.

Parameters

  [in] | config | The rtr_mgr_config.

Returns
  true If pfx_table stores non-outdated pfx_records
  false If pfx_table isn't fully synchronized with at least one group.

Examples
  rtr_mgr.c.

## rtr_mgr_for_each_ipv4_record()

void rtr_mgr_for_each_ipv4_record | ( | struct rtr_mgr_config * | config,
|  | pfx_for_each_fp | fp,
|  | void * | data )

Iterates over all IPv4 records in the pfx_table.

For every pfx_record the function fp is called. The pfx_record and the data pointer is passed to the fp.

Parameters

  [in] | config | rtr_mgr_config
  [in] | fp | Pointer to callback function with signature `pfx_for_each_fp`.
  [in] | data | This parameter is forwarded to the callback function.

## rtr_mgr_for_each_ipv6_record()

void rtr_mgr_for_each_ipv6_record | ( | struct rtr_mgr_config * | config,
|  | pfx_for_each_fp | fp,
|  | void * | data )

Iterates over all IPv6 records in the pfx_table.

For every pfx_record the function fp is called. The pfx_record and the data pointer is passed to the fp.

Parameters

  [in] | config | rtr_mgr_config
  [in] | fp | Pointer to callback function with signature `pfx_for_each_fp`.
  [in] | data | This parameter is forwarded to the callback function.

## rtr_mgr_free()

void rtr_mgr_free | ( | struct rtr_mgr_config * | config | ) |

Frees all resources that were allocated from the rtr_mgr.

rtr_mgr_stop must be called before, to shutdown all rtr_sockets.

Parameters

  [in] | config | rtr_mgr_config.

Examples
  rtr_mgr.c.

## rtr_mgr_get_first_group()

struct rtr_mgr_group * rtr_mgr_get_first_group | ( | struct rtr_mgr_config * | config | ) |

Returns the first, thus active group.

Parameters

  [in] | config | The rtr_mgr_config

Returns
  rtr_mgr_group The head of the linked list.

## rtr_mgr_get_spki()

int rtr_mgr_get_spki | ( | struct rtr_mgr_config * | config,
|  | const uint32_t | asn,
|  | uint8_t * | ski,
|  | struct spki_record ** | result,
|  | unsigned int * | result_count )

Returns all SPKI records which match the given ASN and SKI.

Parameters

  [in] | config |
  [in] | asn | Autonomous system number of the Origin-AS
  [in] | ski | the SKI to search for
  [out] | result | a array of all matching spki_records
  [out] | result_count | number of returned spki_records

Returns
  SPKI_SUCCESS On success
  SPKI_ERROR If an error occurred

## rtr_mgr_init()

int rtr_mgr_init | ( | struct rtr_mgr_config ** | config_out,
|  | struct rtr_mgr_group | groups[],
|  | const unsigned int | groups_len,
|  | const unsigned int | refresh_interval,
|  | const unsigned int | expire_interval,
|  | const unsigned int | retry_interval,
|  | const pfx_update_fp | update_fp,
|  | const spki_update_fp | spki_update_fp,
|  | const rtr_mgr_status_fp | status_fp,
|  | void * | status_fp_data )

Initializes a rtr_mgr_config.

Parameters

  [out] | config_out | The rtr_mgr_config that will be initialized by this function. On error, *config_out will be NULL!
  [in] | groups | Linked list of rtr_mgr_group. Every RTR socket in an rtr_mgr_group must be assoziated with an initialized transport socket. A Transport socket is only allowed to be associated with one rtr socket. The preference values must be unique in the linked list. More than one rtr_mgr_group with the same preference value isn't allowed.
  [in] | groups_len | Number of elements in the groups array. Must be >= 1.
  [in] | refresh_interval | Interval in seconds between serial queries that are sent to the server. Must be >= 1 and <= 86400s (1d), recommended default is 3600s (1h).
  [in] | expire_interval | Stored validation records will be deleted if cache was unable to refresh data for this period. The value should be twice the refresh_interval and must be >= 600s (10min) and <= 172800s (2d). The recommended default is 7200s (2h).
  [in] | retry_interval | This parameter tells the router how long to wait (in seconds) before retrying a failed Serial Query or Reset Query. The value must be >= 1s and <= 7200s (2h). The recommended default is 600s (10min).
  [in] | update_fp | Pointer to pfx_update_fp callback, that is executed for every added and removed pfx_record.
  [in] | spki_update_fp | Pointer to spki_update_fp callback, that is executed for every added and removed spki_record.
  [in] | status_fp | Pointer to a function that is called if the connection status from one of the socket groups is changed.
  [in] | status_fp_data | Pointer to a memory area that is passed to the status_fp function. Memory area can be freely used to pass user-defined data to the status_fp callback.

Returns
  RTR_ERROR If an error occurred
  RTR_INVALID_PARAM If refresh_interval or expire_interval is invalid.
  RTR_SUCCESS On success.

Examples
  rtr_mgr.c.

## rtr_mgr_remove_group()

int rtr_mgr_remove_group | ( | struct rtr_mgr_config * | config,
|  | unsigned int | preference )

Removes an existing rtr_mgr_group from the linked list of config.

The group to be removed is identified by its preference value. Should the group to be removed be currently active, it will be shut down and the next best group will be spun up.

Parameters

  config | A rtr_mgr_config struct that has been initialized previously with rtr_mgr_init
  preference | The preference value of the group to be removed.

Returns
  RTR_ERROR If no group with this preference value exists.
  RTR_SUCCESS If group was successfully removed.

## rtr_mgr_start()

int rtr_mgr_start | ( | struct rtr_mgr_config * | config | ) |

Establishes rtr_socket connections.

Establishes the connection with the rtr_sockets of the group with the lowest preference value and handles errors as defined in the RPKI-RTR protocol.

Parameters

  [in] | config | Pointer to an initialized rtr_mgr_config.

Returns
  RTR_SUCCESS On success
  RTR_ERROR On error

Examples
  rtr_mgr.c.

## rtr_mgr_status_to_str()

const char * rtr_mgr_status_to_str | ( | enum rtr_mgr_status | status | ) |

Converts a rtr_mgr_status to a String.

Parameters

  [in] | status | state to convert to a string.

Returns
  NULL If status isn't a valid rtr_mgr_status.
  !=NULL The rtr_rtr_mgr_status as String.

## rtr_mgr_stop()

void rtr_mgr_stop | ( | struct rtr_mgr_config * | config | ) |

Terminates rtr_socket connections.

Terminates all rtr_socket connections defined in the config. All pfx_records received from these sockets will be purged.

Parameters

  [in] | config | The rtr_mgr_config struct

Examples
  rtr_mgr.c.

## rtr_mgr_validate()

int rtr_mgr_validate | ( | struct rtr_mgr_config * | config,
|  | const uint32_t | asn,
|  | const struct lrtr_ip_addr * | prefix,
|  | const uint8_t | mask_len,
|  | enum pfxv_state * | result )

Validates the origin of a BGP-Route.

Parameters

  [in] | config | The rtr_mgr_config
  [in] | asn | Autonomous system number of the Origin-AS of the prefix
  [in] | prefix | Announced network prefix
  [in] | mask_len | Length of the network mask of the announced prefix
  [out] | result | Outcome of the validation

Returns
  PFX_SUCCESS On success.
  PFX_ERROR If an error occurred.

Examples
  rtr_mgr.c.