package v1sync

Get desktop application:
View/edit binary Protocol Buffers messages

BackrestSyncService provides methods to sync data between backrest instances. This service provides its own authentication and authorization.

• rpc Sync (stream SyncStreamItem, stream SyncStreamItem)

  syncservice.proto:22

  message SyncStreamItem

  syncservice.proto:121

  • oneof action

    • v1.SignedMessage signed_message = 1

    • SyncStreamItem.SyncActionHandshake handshake = 3

      note: mostly deprecated, sent through headers rather than stream.

    • SyncStreamItem.SyncActionHeartbeat heartbeat = 4

    • SyncStreamItem.SyncActionOperationManifest operation_manifest = 20

    • SyncStreamItem.SyncActionReceiveOperations receive_operations = 21

    • SyncStreamItem.SyncActionRequestOperationData request_operation_data = 22

    • SyncStreamItem.SyncActionReceiveConfig receive_config = 23

    • SyncStreamItem.SyncActionSetConfig set_config = 24

    • SyncStreamItem.SyncActionRequestResources request_resources = 25

      request a list of available resources. Only used by the server.

    • SyncStreamItem.SyncActionReceiveResources receive_resources = 26

      receiving a list of available resources.

    • SyncStreamItem.SyncActionRequestLog request_log = 30

    • SyncStreamItem.SyncActionReceiveLogData receive_log_data = 31

    • SyncStreamItem.SyncActionThrottle throttle = 1000

    • SyncStreamItem.SyncEstablishSharedSecret establish_shared_secret = 2

    • SyncStreamItem.SyncActionEncrypted encrypted = 5

BackrestSyncStateService provides methods to query the sync state of known hosts and clients. This service should be served behind authentication and authorization.

• rpc GetPeerSyncStatesStream (SyncStateStreamRequest, stream PeerState)

  syncservice.proto:28

  message SyncStateStreamRequest

  syncservice.proto:34

  • bool subscribe = 1

    If true, the stream will continue to send updates until cancelled.

  message PeerState

  syncservice.proto:38

  • string peer_instance_id = 1

  • string peer_keyid = 2

  • ConnectionState state = 3

  • string status_message = 4

  • repeated PlanMetadata known_plans = 5

    List of plan IDs that the peer has.

  • repeated RepoMetadata known_repos = 6

    List of repo IDs that the peer has.

  • optional RemoteConfig remote_config = 7

    The remote config of the peer, if available.

  • int64 last_heartbeat_millis = 8

    The last time the peer sent a heartbeat, in milliseconds since epoch.

• rpc SetRemoteClientConfig (SetRemoteClientConfigRequest, SetRemoteClientConfigResponse)

  syncservice.proto:30

  SetRemoteClientConfig pushes a config change to a connected authorized client peer.

  message SetRemoteClientConfigRequest

  syncservice.proto:99

  • string peer_keyid = 1

    The key ID of the connected peer to push config to.

  • repeated v1.Repo repos = 2

    Repos to create or update on the peer.

  • repeated v1.Plan plans = 3

    Plans to create or update on the peer.

  • repeated string repos_to_delete = 4

    Repo IDs to delete on the peer.

  • repeated string plans_to_delete = 5

    Plan IDs to delete on the peer.

  message SetRemoteClientConfigResponse

  syncservice.proto:107

  (message has no fields)

• optional v1.SignedMessage instance_id = 1

  The ID of the peer instance.

• optional v1.PublicKey public_key = 1

• optional v1.SignedMessage instance_id = 2

  The ID of the peer instance.

Used in: PeerState

• CONNECTION_STATE_UNKNOWN = 0

• CONNECTION_STATE_PENDING = 1

• CONNECTION_STATE_CONNECTED = 2

• CONNECTION_STATE_DISCONNECTED = 3

• CONNECTION_STATE_RETRY_WAIT = 4

• CONNECTION_STATE_ERROR_AUTH = 10

• CONNECTION_STATE_ERROR_PROTOCOL = 11

• CONNECTION_STATE_ERROR_INTERNAL = 12

• repeated int64 op_ids = 1

  The IDs of the operations.

• repeated int64 modnos = 2

  The modnos of the operations.

• string log_id = 1

  The ID of the log, only used for the first message in a log data stream.

• int64 owner_opid = 2

  The operation ID of the operation that owns this log data.

• int64 expiration_ts_unix = 3

  Unix timestamp in seconds when the log data expires.

• bytes chunk = 4

  The log data chunk, can be sent repeatedly, must be terminated by a packet with size = 0.

Used in: PeerState, SetAvailableResourcesRequest, SyncStreamItem.SyncActionReceiveResources

• string id = 1

Used in: PeerState, SyncStreamItem.SyncActionReceiveConfig

• int32 modno = 1

  The modno of the config.

• int32 version = 2

  The storage version of the config.

• repeated v1.Repo repos = 3

• repeated v1.Plan plans = 4

Used in: PeerState, SetAvailableResourcesRequest, SyncStreamItem.SyncActionReceiveResources

• string id = 1

• string guid = 2

• repeated PlanMetadata repos = 1

  The repos that are available.

• repeated RepoMetadata plans = 2

  The plans that are available.

• repeated v1.Plan plans = 1

  The plans to set.

• repeated v1.Repo repos = 2

  The repos to set.

• repeated string repos_to_delete = 3

  The repo IDs to delete.

• repeated string plans_to_delete = 4

  The plan IDs to delete.

• CONNECTION_STATE_UNKNOWN = 0

• CONNECTION_STATE_PENDING = 1

  queried, response not yet received.

• CONNECTION_STATE_CONNECTED = 2

• CONNECTION_STATE_UNAUTHORIZED = 3

• CONNECTION_STATE_NOT_FOUND = 4

• string repo_id = 1

SyncActionEncrypted wraps an encrypted SyncStreamItem. After the post-quantum KEM handshake, all subsequent messages are sent inside this envelope.

Used in: SyncStreamItem

• bytes nonce = 1

  12-byte GCM nonce

• bytes ciphertext = 2

  AES-256-GCM(serialized SyncStreamItem)

SyncActionHandshake is the first message sent by each peer over the post-quantum encrypted channel. It carries the sender's long-term ed25519 identity, its instance ID, and a single signature that binds the identity to *this* transport session. The signature covers a domain-separated hash of: "backrest-sync-handshake/v1\x00" || protocol_version (8 bytes BE) || LP(instance_id) || LP(pairing_secret) || LP(transport transcript) where LP(x) = 4-byte BE length prefix || x, and the transport transcript is cryptoutil.TransportSession.Transcript() — a hash that commits to the ephemeral KEM messages of this connection. The transcript binding is what defeats a MITM that completes a separate KEM with each side: each leg has a different transcript, and the legitimate peer's signature only commits to its own transcript, so the attacker cannot forward a usable signature to either side. Receivers MUST recompute the transcript locally from their TransportSession and reject the handshake if the signature does not verify against public_key. There is no timestamp because freshness is provided by the ephemeral KEM, not by clock comparison.

Used in: SyncStreamItem

• int64 protocol_version = 1

• optional v1.PublicKey public_key = 2

  sender's long-term ed25519 identity

• string instance_id = 3

  covered by signature below

• string pairing_secret = 4

  optional pairing token; covered by signature below

• bytes signature = 5

  ed25519(public_key, H(handshake bind input))

SyncActionHeartbeat is sent periodically to keep the connection alive.

Used in: SyncStreamItem

(message has no fields)

Used in: SyncStreamItem

• repeated int64 op_ids = 1

• repeated int64 modnos = 2

Used in: SyncStreamItem

• optional RemoteConfig config = 1

Used in: SyncStreamItem

• string log_id = 1

• int64 owner_opid = 2

  Required only for first message in a log data stream.

  The operation ID of the operation that owns this log data.

• int64 expiration_ts_unix = 3

  Unix timestamp in seconds when the log data expires.

• bytes chunk = 4

  Can be sent repeatedly, must be terminated by a packet with size = 0.

• string error_message = 5

  If set, indicates an error occurred while fetching the log data.

Used in: SyncStreamItem

• optional v1.OperationEvent event = 1

Used in: SyncStreamItem

• repeated RepoMetadata repos = 1

• repeated PlanMetadata plans = 2

Used in: SyncStreamItem

• string log_id = 1

Used in: SyncStreamItem

• repeated int64 op_ids = 1

Used in: SyncStreamItem

(message has no fields)

Used in: SyncStreamItem

• repeated v1.Repo repos = 1

• repeated v1.Plan plans = 2

• repeated string repos_to_delete = 3

• repeated string plans_to_delete = 4

Used in: SyncStreamItem

• int64 delay_ms = 1

SyncEstablishSharedSecret is exchanged immediately after the connection is opened. The initiator (client) sends kem_public_key. The responder (server) replies with kem_encapsulation. Both sides then derive a shared AES-256-GCM session key via the HPKE Export interface. All subsequent messages must be wrapped in SyncActionEncrypted. The KEM is the post-quantum hybrid ML-KEM-1024 + ECDH-P384 (HPKE ciphersuite ML-KEM-1024-P384 / KEM ID 0x0050, RFC 9180 + the IETF hybrid KEM drafts). KDF is HKDF-SHA256, AEAD is AES-256-GCM. Peers must use protocol_version=1; mismatched versions abort the connection.

Used in: SyncStreamItem

• uint32 protocol_version = 1

  current: 1

• bytes kem_public_key = 2

  set by initiator

• bytes kem_encapsulation = 3

  set by responder