package command

Get desktop application:
View/edit binary Protocol Buffers messages

Used in: Request

• required SocketAddress address = 1

• required ListenerType proxy = 2

• required bool from_scm = 3

add a backend

Used in: ClusterInformation, Request

• required string cluster_id = 1

• required string backend_id = 2

• required SocketAddress address = 3

  the socket address of the backend

• optional string sticky_id = 4

• optional LoadBalancingParams load_balancing_parameters = 5

• optional bool backup = 6

Add a new TLS certificate to an HTTPs listener

Used in: Request

• required SocketAddress address = 1

• required CertificateAndKey certificate = 2

• optional int64 expired_at = 3

  A unix timestamp. Overrides certificate expiration.

Aggregated metrics of main process & workers

Used in: ResponseContent

• map<string, FilteredMetrics> main = 1

  metrics about the main process. metric_name -> metric_value

• map<string, WorkerMetrics> workers = 2

  details of worker metrics, with clusters and backends. worker_id -> worker_metrics

• map<string, ClusterMetrics> clusters = 3

  if present, contains metrics of clusters and their backends, merged across all workers. cluster_id -> cluster_metrics

• map<string, FilteredMetrics> proxying = 4

  if present, proxying metrics, merged accross all workers. metric_name -> metric_value

lists of available metrics in a worker, or in the main process (in which case there are no cluster metrics)

Used in: ResponseContent

• repeated string proxy_metrics = 1

• repeated string cluster_metrics = 2

Used in: ClusterMetrics

• required string backend_id = 1

• map<string, FilteredMetrics> metrics = 2

a prometheus histogram bucket

Used in: FilteredHistogram

• required uint64 count = 1

• required uint64 le = 2

  upper range of the bucket (le = less or equal)

Used in: AddCertificate, CertificatesWithFingerprints, ReplaceCertificate

• required string certificate = 1

• repeated string certificate_chain = 2

• required string key = 3

• repeated TlsVersion versions = 4

• repeated string names = 5

  a list of domain names. Override certificate names if empty, the names of the certificate will be used

domain name and fingerprint of a certificate

Used in: CertificatesByAddress

• required string domain = 1

• required string fingerprint = 2

  a hex-encoded TLS fingerprint

Summaries of certificates for a given address

Used in: ListOfCertificatesByAddress

• required SocketAddress address = 1

• repeated CertificateSummary certificate_summaries = 2

to reply to several certificate queries

Used in: ResponseContent

• map<string, CertificateAndKey> certs = 1

  a map of fingerprint -> certificate_and_key

A cluster is what binds a frontend to backends with routing rules

Used in: ClusterInformation, Request

• required string cluster_id = 1

• required bool sticky_session = 2

  wether a connection from a client shall be always redirected to the same backend

• required bool https_redirect = 3

• optional ProxyProtocolConfig proxy_protocol = 4

• required LoadBalancingAlgorithms load_balancing = 5

• optional string answer_503 = 6

• optional LoadMetric load_metric = 7

Used in: ResponseContent

• map<string, uint64> map = 1

  cluster id -> hash of cluster information

Information about a given cluster Contains types usually used in requests, because they are readily available in protobuf

Used in: ClusterInformations

• optional Cluster configuration = 1

• repeated RequestHttpFrontend http_frontends = 2

• repeated RequestHttpFrontend https_frontends = 3

• repeated RequestTcpFrontend tcp_frontends = 4

• repeated AddBackend backends = 5

Used in: ResponseContent

• repeated ClusterInformation vec = 1

the metrics of a given cluster, with several backends

Used in: AggregatedMetrics, WorkerMetrics

• map<string, FilteredMetrics> cluster = 1

  metric name -> metric value

• repeated BackendMetrics backends = 2

  list of backends with their metrics

Used in: Request

(message has no fields)

custom HTTP answers, useful for 404, 503 pages

Used in: HttpListenerConfig, HttpsListenerConfig

• optional string answer_301 = 1

  MovedPermanently

• optional string answer_400 = 2

  BadRequest

• optional string answer_401 = 3

  Unauthorized

• optional string answer_404 = 4

  NotFound

• optional string answer_408 = 5

  RequestTimeout

• optional string answer_413 = 6

  PayloadTooLarge

• optional string answer_502 = 7

  BadGateway

• optional string answer_503 = 8

  ServiceUnavailable

• optional string answer_504 = 9

  GatewayTimeout

• optional string answer_507 = 10

  InsufficientStorage

Used in: Request

• required SocketAddress address = 1

• required ListenerType proxy = 2

• required bool to_scm = 3

an event produced by a worker to notify about backends status

Used in: ResponseContent

• required EventKind kind = 1

• optional string cluster_id = 2

• optional string backend_id = 3

• optional SocketAddress address = 4

Used in: Event

• BACKEND_DOWN = 0

• BACKEND_UP = 1

• NO_AVAILABLE_BACKENDS = 2

• REMOVED_BACKEND_HAS_NO_CONNECTIONS = 3

a histogram meant to be translated to prometheus

Used in: FilteredMetrics

• required uint64 sum = 1

• required uint64 count = 2

• repeated Bucket buckets = 3

A metric, in a "filtered" format, which means: sendable to outside programs.

Used in: AggregatedMetrics, BackendMetrics, ClusterMetrics, WorkerMetrics

• oneof inner

  • uint64 gauge = 1

    increases or decrease depending on the state

  • int64 count = 2

    increases only

  • uint64 time = 3

    milliseconds

  • Percentiles percentiles = 4

  • FilteredTimeSerie time_serie = 5

  • FilteredHistogram histogram = 6

Used in: FilteredMetrics

• required uint32 last_second = 1

• repeated uint32 last_minute = 2

• repeated uint32 last_hour = 3

list the frontends, filtered by protocol and/or domain

Used in: Request

• required bool http = 1

• required bool https = 2

• required bool tcp = 3

• optional string domain = 4

Used in: Request

(message has no fields)

Used in: ProtobufEndpoint

• optional string method = 1

• optional string authority = 2

• optional string path = 3

• optional uint32 status = 4

  warning: this should be a u16 but protobuf only has uint32. Make sure the value never exceeds u16 bounds.

• optional string reason = 5

details of an HTTP listener

Used in: ListenersList, Request

• required SocketAddress address = 1

• optional SocketAddress public_address = 2

• required bool expect_proxy = 5

• required string sticky_name = 6

• required uint32 front_timeout = 7

  client inactive time, in seconds

• required uint32 back_timeout = 8

  backend server inactive time, in seconds

• required uint32 connect_timeout = 9

  time to connect to the backend, in seconds

• required uint32 request_timeout = 10

  max time to send a complete request, in seconds

• required bool active = 11

  wether the listener is actively listening on its socket

• optional CustomHttpAnswers http_answers = 12

details of an HTTPS listener

Used in: ListenersList, Request

• required SocketAddress address = 1

• optional SocketAddress public_address = 2

• required bool expect_proxy = 5

• required string sticky_name = 6

• required uint32 front_timeout = 7

  client inactive time, in seconds

• required uint32 back_timeout = 8

  backend server inactive time, in seconds

• required uint32 connect_timeout = 9

  time to connect to the backend, in seconds

• required uint32 request_timeout = 10

  max time to send a complete request, in seconds

• required bool active = 11

  wether the listener is actively listening on its socket

• repeated TlsVersion versions = 12

  TLS versions

• repeated string cipher_list = 13

• repeated string cipher_suites = 14

• repeated string signature_algorithms = 15

• repeated string groups_list = 16

• optional string certificate = 17

• repeated string certificate_chain = 18

• optional string key = 19

• required uint64 send_tls13_tickets = 20

  Number of TLS 1.3 tickets to send to a client when establishing a connection. The tickets allow the client to resume a session. This protects the client agains session tracking. Defaults to 4.

• optional CustomHttpAnswers http_answers = 21

the Sōzu state, passed to a new worker. Consists in a collection of worker requests

• repeated WorkerRequest requests = 1

Used in: SocketAddress

• oneof inner

  • fixed32 v4 = 1

  • Uint128 v6 = 2

Used in: Request

(message has no fields)

Used by workers to reply to some certificate queries

Used in: ResponseContent

• repeated CertificatesByAddress certificates = 1

Used in: Request

(message has no fields)

lists of frontends present in the state

Used in: ResponseContent

• repeated RequestHttpFrontend http_frontends = 1

• repeated RequestHttpFrontend https_frontends = 2

• repeated RequestTcpFrontend tcp_frontends = 3

Used in: ActivateListener, DeactivateListener, RemoveListener

• HTTP = 0

• HTTPS = 1

• TCP = 2

Addresses of listeners, passed to new workers

• repeated string http = 1

  socket addresses of HTTP listeners

• repeated string tls = 2

  socket addresses of HTTPS listeners

• repeated string tcp = 3

  socket addresses of TCP listeners

All listeners, listed

Used in: ResponseContent

• map<string, HttpListenerConfig> http_listeners = 1

  address -> http listener config

• map<string, HttpsListenerConfig> https_listeners = 2

  address -> https listener config

• map<string, TcpListenerConfig> tcp_listeners = 3

  address -> tcp listener config

Used in: Cluster

• ROUND_ROBIN = 0

• RANDOM = 1

• LEAST_LOADED = 2

• POWER_OF_TWO = 3

Used in: AddBackend

• required int32 weight = 1

how sozu measures which backend is less loaded

Used in: Cluster

• CONNECTIONS = 0

  number of TCP connections

• REQUESTS = 1

  number of active HTTP requests

• CONNECTION_TIME = 2

  time to connect to the backend, weighted by the number of active connections (peak EWMA)

options to configure metrics collection

Used in: Request

• ENABLED = 0

  enable metrics collection

• DISABLED = 1

  disable metrics collection

• CLEAR = 2

  wipe the metrics memory

A filter for the path of incoming requests

Used in: RequestHttpFrontend

• required PathRuleKind kind = 1

  The kind of filter used for path rules

• required string value = 2

  the value of the given prefix, regex or equal pathrule

The kind of filter used for path rules

Used in: PathRule

• PREFIX = 0

  filters paths that start with a pattern, typically "/api"

• REGEX = 1

  filters paths that match a regex pattern

• EQUALS = 2

  filters paths that exactly match a pattern, no more, no less

Used in: FilteredMetrics

• required uint64 samples = 1

• required uint64 p_50 = 2

• required uint64 p_90 = 3

• required uint64 p_99 = 4

• required uint64 p_99_9 = 5

• required uint64 p_99_99 = 6

• required uint64 p_99_999 = 7

• required uint64 p_100 = 8

• required uint64 sum = 9

An access log, meant to be passed to another agent

• optional string message = 1

  error message if any

• required Uint128 request_id = 2

  LogContext = request_id + cluster_id + backend_id

• optional string cluster_id = 3

  id of the cluster (set of frontend, backend, routing rules)

• optional string backend_id = 4

  id of the backend (the server to which the traffic is redirected)

• optional SocketAddress session_address = 5

  ip and port of the client

• optional SocketAddress backend_address = 6

  socket address of the backend server

• required string protocol = 7

  the protocol, with SSL/TLS version, for instance "HTTPS-TLS1.1"

• required ProtobufEndpoint endpoint = 8

  TCP or HTTP endpoint (method, path, context...)

• optional uint64 client_rtt = 9

  round trip time for the client (microseconds)

• optional uint64 server_rtt = 10

  round trip time for the backend (microseconds)

• required uint64 service_time = 13

  time spent on a session (microseconds)

• required uint64 bytes_in = 14

  number of bytes received from the client

• required uint64 bytes_out = 15

  number of bytes written to the client

• optional string user_agent = 16

  value of the User-Agent header, if any

• map<string, string> tags = 17

  custom tags as key-values, for instance owner_id: MyOrganisation

• required string tag = 18

  short description of which process sends the log, for instance: "WRK-02"

• required Uint128 time = 19

  POSIX timestamp, nanoseconds

• optional uint64 request_time = 20

  Entire time between first byte received and last byte of the response. If a request ends abruptly before the last byte is transmitted, the `request_time` produced is the time elapsed since the first byte received.

• optional uint64 response_time = 21

  time for the backend to respond (microseconds)

Used in: ServerConfig

• Ascii = 1

• Protobuf = 2

Used in: ProtobufAccessLog

• oneof inner

  • HttpEndpoint http = 1

  • TcpEndpoint tcp = 2

Used in: Cluster

• EXPECT_HEADER = 0

• SEND_HEADER = 1

• RELAY_HEADER = 2

Should be either a domain name or a fingerprint. These filter do not compound, use either one but not both. If none of them is specified, all certificates will be returned.

Used in: Request

• optional string domain = 1

  a domain name to filter certificate results

• optional string fingerprint = 2

  a hex-encoded fingerprint of the TLS certificate to find

Used in: Request

• required string hostname = 1

• optional string path = 2

Used in: Request

(message has no fields)

Options when querying metrics

Used in: Request

• required bool list = 1

  query a list of available metrics

• repeated string cluster_ids = 2

  query metrics for these clusters

• repeated string backend_ids = 3

  query metrics for these backends

• repeated string metric_names = 4

  query only these metrics

• required bool no_clusters = 5

  query only worker and main process metrics (no cluster metrics)

• required bool workers = 6

  display metrics of each worker, without flattening (takes more space)

remove an existing backend

Used in: Request

• required string cluster_id = 1

• required string backend_id = 2

• required SocketAddress address = 3

  the socket address of the backend

Used in: Request

• required SocketAddress address = 1

• required string fingerprint = 2

  a hex-encoded TLS fingerprint to identify the certificate to remove

Used in: Request

• required SocketAddress address = 1

• required ListenerType proxy = 2

Used in: Request

• required SocketAddress address = 1

• required CertificateAndKey new_certificate = 2

• required string old_fingerprint = 3

  a hex-encoded TLS fingerprint to identify the old certificate

• optional int64 new_expired_at = 4

  A unix timestamp. Overrides certificate expiration.

A message received by Sōzu to change its state or query information

Used in: WorkerRequest

• oneof request_type

  • string save_state = 1

    This message tells Sōzu to dump the current proxy state (backends, front domains, certificates, etc) as a list of JSON-serialized Requests, separated by a 0 byte, to a file. This file can be used later to bootstrap the proxy. This message is not forwarded to workers. If the specified path is relative, it will be calculated relative to the current working directory of the proxy.

  • string load_state = 2

    load a state file, given its path

  • ListWorkers list_workers = 4

    list the workers and their status

  • FrontendFilters list_frontends = 5

    list the frontends, filtered by protocol and/or domain

  • ListListeners list_listeners = 6

    list all listeners

  • string launch_worker = 7

    launch a new worker never implemented, the tag is unused and probably not needed we may still implement it later with no paramater the main process will automatically assign a new id to a new worker

  • UpgradeMain upgrade_main = 8

    upgrade the main process

  • uint32 upgrade_worker = 9

    upgrade an existing worker, giving its id

  • SubscribeEvents subscribe_events = 10

    subscribe to proxy events

  • string reload_configuration = 11

    reload the configuration from the config file, or a new file CHECK: this used to be an option. None => use the config file, Some(string) => path_to_file make sure it works using "" and "path_to_file"

  • Status status = 12

    give status of main process and all workers

  • Cluster add_cluster = 13

    add a cluster

  • string remove_cluster = 14

    remove a cluster giving its id

  • RequestHttpFrontend add_http_frontend = 15

    add an HTTP frontend

  • RequestHttpFrontend remove_http_frontend = 16

    remove an HTTP frontend

  • RequestHttpFrontend add_https_frontend = 17

    add an HTTPS frontend

  • RequestHttpFrontend remove_https_frontend = 18

    remove an HTTPS frontend

  • AddCertificate add_certificate = 19

    add a certificate

  • ReplaceCertificate replace_certificate = 20

    replace a certificate

  • RemoveCertificate remove_certificate = 21

    remove a certificate

  • RequestTcpFrontend add_tcp_frontend = 22

    add a TCP frontend

  • RequestTcpFrontend remove_tcp_frontend = 23

    remove a TCP frontend

  • AddBackend add_backend = 24

    add a backend

  • RemoveBackend remove_backend = 25

    remove a backend

  • HttpListenerConfig add_http_listener = 26

    add an HTTP listener

  • HttpsListenerConfig add_https_listener = 27

    add an HTTPS listener

  • TcpListenerConfig add_tcp_listener = 28

    add a TCP listener

  • RemoveListener remove_listener = 29

    remove a listener

  • ActivateListener activate_listener = 30

    activate a listener

  • DeactivateListener deactivate_listener = 31

    deactivate a listener

  • string query_cluster_by_id = 35

    query a cluster by id

  • QueryClusterByDomain query_clusters_by_domain = 36

    query clusters with a hostname and optional path

  • QueryClustersHashes query_clusters_hashes = 37

    query clusters hashes

  • QueryMetricsOptions query_metrics = 38

    query metrics

  • SoftStop soft_stop = 39

    soft stop

  • HardStop hard_stop = 40

    hard stop

  • MetricsConfiguration configure_metrics = 41

    enable, disable or clear the metrics

  • string Logging = 42

    Change the logging level

  • ReturnListenSockets return_listen_sockets = 43

    Return the listen sockets

  • QueryCertificatesFilters query_certificates_from_the_state = 44

    Get certificates from the state (rather than from the workers)

  • QueryCertificatesFilters query_certificates_from_workers = 45

    Get certificates from the workers (rather than from the state)

  • CountRequests count_requests = 46

    query the state about how many requests of each type has been received since startup

Used in: ResponseContent

• map<string, int32> map = 1

An HTTP or HTTPS frontend, as order to, or received from, Sōzu

Used in: ClusterInformation, ListedFrontends, Request

• optional string cluster_id = 1

• required SocketAddress address = 2

• required string hostname = 3

• required PathRule path = 4

• optional string method = 5

• required RulePosition position = 6

• map<string, string> tags = 7

  custom tags to identify the frontend in the access logs

Used in: ClusterInformation, ListedFrontends, Request

• required string cluster_id = 1

• required SocketAddress address = 2

  the socket address on which to listen for incoming traffic

• map<string, string> tags = 3

  custom tags to identify the frontend in the access logs

Response to a request

• required ResponseStatus status = 1

  wether the request was a success, a failure, or is processing

• required string message = 2

  a success or error message

• optional ResponseContent content = 3

  response data, if any

content of a response

Used in: Response, WorkerResponse, WorkerResponses

• oneof content_type

  • WorkerInfos workers = 1

    a list of workers, with ids, pids, statuses

  • AggregatedMetrics metrics = 2

    aggregated metrics of main process and workers

  • WorkerResponses worker_responses = 3

    a collection of worker responses to the same request

  • Event event = 4

    a proxy event

  • ListedFrontends frontend_list = 5

    a filtered list of frontend

  • ListenersList listeners_list = 6

    all listeners

  • WorkerMetrics worker_metrics = 7

    contains proxy & cluster metrics

  • AvailableMetrics available_metrics = 8

    Lists of metrics that are available

  • ClusterInformations clusters = 9

    a list of cluster informations

  • ClusterHashes cluster_hashes = 10

    collection of hashes of cluster information,

  • ListOfCertificatesByAddress certificates_by_address = 11

    a list of certificates summaries, grouped by socket address

  • CertificatesWithFingerprints certificates_with_fingerprints = 12

    a map of complete certificates using fingerprints as key

  • RequestCounts request_counts = 13

    a census of the types of requests received since startup,

Used in: Response, WorkerResponse

• OK = 0

• PROCESSING = 1

• FAILURE = 2

Used in: Request

(message has no fields)

TODO: find a proper definition for this

Used in: RequestHttpFrontend

• PRE = 0

• POST = 1

• TREE = 2

Runstate of a worker

Used in: WorkerInfo

• RUNNING = 0

• STOPPING = 1

• STOPPED = 2

• NOT_ANSWERING = 3

Used by a worker to start its server loop. The defaults should match those of the config module

• required uint64 max_connections = 1

• required uint32 front_timeout = 2

• required uint32 back_timeout = 3

• required uint32 connect_timeout = 4

• required uint32 zombie_check_interval = 5

• required uint32 accept_queue_timeout = 6

• required uint64 min_buffers = 7

• required uint64 max_buffers = 8

• required uint64 buffer_size = 9

• required string log_level = 10

• required string log_target = 11

• optional string access_logs_target = 12

• required uint64 command_buffer_size = 13

• required uint64 max_command_buffer_size = 14

• optional ServerMetricsConfig metrics = 15

• required ProtobufAccessLogFormat access_log_format = 16

• required bool log_colored = 17

intended to workers

Used in: ServerConfig

• required string address = 1

• required bool tagged_metrics = 2

• optional string prefix = 3

matches std::net::SocketAddr in the Rust library beware that the ports are expressed with uint32 here, but they should NOT exceed uint16 value

Used in: ActivateListener, AddBackend, AddCertificate, CertificatesByAddress, DeactivateListener, Event, HttpListenerConfig, HttpsListenerConfig, ProtobufAccessLog, RemoveBackend, RemoveCertificate, RemoveListener, ReplaceCertificate, RequestHttpFrontend, RequestTcpFrontend, TcpListenerConfig

• required IpAddress ip = 1

• required uint32 port = 2

Used in: Request

(message has no fields)

Used in: Request

(message has no fields)

Used in: Request

(message has no fields)

Used in: ProtobufEndpoint

(message has no fields)

details of an TCP listener

Used in: ListenersList, Request

• required SocketAddress address = 1

• optional SocketAddress public_address = 2

• required bool expect_proxy = 3

• required uint32 front_timeout = 4

  client inactive time, in seconds

• required uint32 back_timeout = 5

  backend server inactive time, in seconds

• required uint32 connect_timeout = 6

  time to connect to the backend, in seconds

• required bool active = 7

  wether the listener is actively listening on its socket

Used in: CertificateAndKey, HttpsListenerConfig

• SSL_V2 = 0

• SSL_V3 = 1

• TLS_V1_0 = 2

• TLS_V1_1 = 3

• TLS_V1_2 = 4

• TLS_V1_3 = 5

used to represent the 128 bits of an IPv6 address

Used in: IpAddress, ProtobufAccessLog

• required uint64 low = 1

  higher value, first 8 bytes of the ip

• required uint64 high = 2

  lower value, last 8 bytes of the ip

Used in: Request

(message has no fields)

Information about a worker with id, pid, runstate

Used in: WorkerInfos

• required uint32 id = 1

• required int32 pid = 2

• required RunState run_state = 3

A list of worker infos

Used in: ResponseContent

• repeated WorkerInfo vec = 1

All metrics of a worker: proxy and clusters Populated by Options so partial results can be sent

Used in: AggregatedMetrics, ResponseContent

• map<string, FilteredMetrics> proxy = 1

  Metrics of the worker process, key -> value

• map<string, ClusterMetrics> clusters = 2

  cluster_id -> cluster_metrics

This is sent only from Sōzu to Sōzu

Used in: InitialState

• required string id = 1

• required Request content = 2

A response as sent by a worker

• required string id = 1

• required ResponseStatus status = 2

• required string message = 3

  an associated message to detail failure, success or processing

• optional ResponseContent content = 4

a map of worker_id -> ResponseContent

Used in: ResponseContent

• map<string, ResponseContent> map = 1