Skip to article frontmatterSkip to article content
Site not loading correctly?

This may be due to an incorrect BASE_URL configuration. See the MyST Documentation for reference.

archive_keeper

archive_keeper keeps the batches of timeranger2 archives that archive_senders (yunos/c/archive_sender/) ship with the native transport. It runs on the backup machine. Each channel is one sender, and each sender has at most one batch in flight. The README of archive_sender describes the frames.

To run it, give it a backup_directory, the allowed_nodes, and a TLS listener that asks the senders for a certificate of the CA of the nodes. The section “Configuration” below has a full example.

Where the batches go

<backup_directory>/<node>/<database>/<topic>/<key>/<batch>/
<backup_directory>/<node>/<database>/<topic>/<key>/.part-<batch>/     one in flight

What it refuses

The peer writes everything in a frame. The keeper refuses the items below with a WARNING, the answer refused, and the removal of the batch aside:

The keeper refuses a batch once. It also answers refused to the frames of the batch that the sender already sent (its window), but it does not log or count them again.

A frame whose header is not a json object drops the channel.

Configuration

AttributeDefaultMeaning
backup_directory—Absolute. Created if it is not there
allowed_nodes[]The node names whose batches the keeper takes. ["*"] takes any node. Required: if it is empty, the yuno does not start (ERROR)
input_service__input_side__The C_IOGATE whose channels are the senders
max_files100000The most files that a batch can declare. The first archive of an hourly topic holds two files per hour (.json and .md2): 100000 is more than five years. Each file in flight costs the keeper some hundreds of bytes of memory
stale_session_timeout60000Milliseconds without a frame. After them, the next begin of any channel drops the channel. That begin takes over its batch in flight (if the begin is of that batch), and the space that it reserved is free again. 0: never
require_client_certificatetrueThe node of a batch must be the cn or a DNS name of the verified client certificate of its channel (mutual TLS). false: the node is the claim of the sender, said on purpose
{
    "global": {
        "archive_keeper.backup_directory": "/backups/yuneta",
        "archive_keeper.allowed_nodes": ["node-b", "node-a"],
        "__input_side__.__json_config_variables__": {
            "__input_url__": "tcps://0.0.0.0:1999",
            "__ssl_certificate__": "/yuneta/store/certs/backup.example.com.crt",
            "__ssl_certificate_key__": "/yuneta/store/certs/private/backup.example.com.key",
            "__nodes_ca__": "/yuneta/store/certs/nodes_ca.pem"
        }
    },
    "services": [
        {
            "name": "__input_side__",
            "gclass": "C_IOGATE",
            "autostart": false,
            "autoplay": false,
            "children": [
                {
                    "name": "input_server",
                    "gclass": "C_TCP_S",
                    "kw": {
                        "url": "(^^__input_url__^^)",
                        "crypto": {
                            "library": "(^^__tls_library__^^)",
                            "ssl_certificate": "(^^__ssl_certificate__^^)",
                            "ssl_certificate_key": "(^^__ssl_certificate_key__^^)",
                            "ssl_trusted_certificate": "(^^__nodes_ca__^^)",
                            "ssl_verify_mode": "required"
                        },
                        "child_tree_filter": {
                            "kw": {
                                "__gclass_name__": "C_CHANNEL",
                                "__disabled__": false,
                                "connected": false
                            }
                        }
                    }
                }
            ],
            "[^^children^^]": {
                "__range__": 20,
                "__vars__": {},
                "__content__": {
                    "name": "input-(^^__range__^^)",
                    "gclass": "C_CHANNEL",
                    "children": [
                        {
                            "name": "input-(^^__range__^^)",
                            "gclass": "C_PROT_TCP4H",
                            "children": [
                                {
                                    "name": "input-(^^__range__^^)",
                                    "gclass": "C_TCP"
                                }
                            ]
                        }
                    ]
                }
            }
        }
    ]
}

__range__ is the number of senders that can be connected at one time.

Security: the node of a batch is bound to the client certificate of its channel (mutual TLS):

The CA of the nodes is a private one. A public CA does not certify a node name, and Let’s Encrypt no longer issues certificates for client authentication. Each node gets a certificate with its node_name as cn, and extendedKeyUsage=clientAuth. For example, with the openssl command:

# Once, on the backup machine: the CA of the nodes
openssl req -x509 -newkey rsa:3072 -nodes -sha256 -days 3650 \
    -keyout nodes_ca.key -out nodes_ca.pem -subj '/CN=Yuneta nodes CA' \
    -addext 'basicConstraints=critical,CA:TRUE' \
    -addext 'keyUsage=critical,keyCertSign,cRLSign'

# For each node (here "node-b"): its key, and its certificate
openssl req -newkey rsa:3072 -nodes -sha256 -keyout node-b.key -out node-b.csr -subj '/CN=node-b'
printf 'basicConstraints=CA:FALSE\nextendedKeyUsage=clientAuth\n' > client.ext
openssl x509 -req -in node-b.csr -CA nodes_ca.pem -CAkey nodes_ca.key -CAcreateserial \
    -days 825 -sha256 -extfile client.ext -out node-b.crt

Even so, put the port of the keeper where only the nodes can reach it.

Commands and stats

CommandDoes
list-sessionsThe batches that the keeper receives, one per channel, with what each file has

Stats: batches_stored, bytes_stored, batches_already (offered and already here), batches_refused (batches, not frames: once per batch refused).

Traces: batches and frames, as in archive_sender.

Tests

tests/c/archive_shipping/ has two tests: