Control Service

Port table

Description	Transport	Port	Application protocol
Service resolution	UDP/SCION	30252	Resolution protobufs
Control-plane (inter-AS) Discovery API	UDP/SCION	random	QUIC + gRPC with HTTP/2
Control-plane (intra-AS) Health API	TCP	30252	gRPC with HTTP/2
Monitoring	TCP	30452	HTTP/2

Metrics

Warning

The list of control service metrics is incomplete.

Renewal

Renewal requests

Name: renewal_received_requests_total

Type: Counter

Description: Total number of certificate renewal requests served. Only for control services with CA functionality enabled.

Labels: result.

Renewal requests per handler type

Name: renewal_handled_requests_total

Type: Counter

Description: Total number of renewal requests served by each handler type (legacy, in-process, delegating).

Labels: type and result.

Note

The sum of all renewal_handled_requests_total is not necessarily equal to the sum of all renewal_received_requests_total. This is because renewal_received_requests_total counts all incoming request and renewal_handled_requests_total only counts requests that could have been parsed and delegated to a handler.

Renewal request registered handlers

Name: renewal_registered_handlers

Type: Gauge

Description: Exposes which handler type (legacy, in-process, delegating) is registered.

Labels: type.

TRC local filesystem writes

Name: trustengine_trc_file_writes_total

Type: Counter

Description: Total number of TRC local filesystem write results. A result can be one of (ok_success, err_write, err_stat).

Labels: result.

HTTP API

The HTTP API is exposed by the control application on the IP address and port of the metrics.prometheus configuration setting.

The HTTP API does not support user authentication or HTTPS. Applications will want to firewall this port or bind to a loopback address.

In addition to the common HTTP API, the control application supports the following API calls:

/topology (EXPERIMENTAL)
- Method GET. Prints a JSON representation of current topology state, displayed in a format that is similar to the topology file. Note that there are slight differences between the output format and the topology file format, which means the output cannot be copy/pasted and used as a topology file.

/signer (EXPERIMENTAL)

Method GET. Prints JSON data about the Subject Key (i.e., the key used by the application to sign messages) and the TRC in use, in addition to other miscellaneous data that is relevant for signing. Private keys are not printed. Example output:

{
  "subject": {
    "isd_as": "1-ff00:0:110"
  },
  "subject_key_id": "21 36 9B 82 D3 B9 90 58 16 D0 90 C0 15 66 C3 DC 0E 46 A5 9B",
  "expiration": "2021-09-28T13:19:16Z",
  "trc_id": {
    "isd": 1,
    "base_number": 1,
    "serial_number": 1
  },
  "chain_validity": {
    "not_before": "2020-09-28T13:19:16Z",
    "not_after": "2021-09-28T13:19:16Z"
  },
  "in_grace_period": false
}

For ASes that operate as CAs, the following API calls are also exposed:

/ca (EXPERIMENTAL)

Method GET. Prints JSON data about the Subject Key (i.e., the key used by the CA to sign certificates) and the CA policy. Example output:

{
  "subject": {
    "isd_as": "1-ff00:0:110"
  },
  "subject_key_id": "8C 5A 07 FF 83 F7 C8 69 0A 28 01 4F CF 0F BF AB FF D5 E6 FF",
  "policy": {
    "chain_lifetime": "72h0m0s"
  },
  "cert_validity": {
    "not_before": "2020-09-28T13:19:16Z",
    "not_after": "2022-09-28T13:19:16Z"
  }
}