Site server (bkp_sitesrv)

Go to the contents

What the machines of an account share among themselves is synchronized by the site server: the targets an account distributes to its own machines (section “Distributing a target within your own account”), and the job schedulers released for management consoles. Licenses, points, orders, branding and targets released to other accounts stay with the license server.

By default every account uses the hosted site server of AegisGrid (site.aegisgrid.de); nothing has to be set up for it. A site server of your own is needed by whoever wants to keep these details (addresses, fingerprints and keys of their own targets and schedulers) in their own network or has a network without a connection to the internet. A partner can run a site server for their customers.

Which site server is responsible for an account is set by the license server in a signed assignment. The machines fetch it at their hourly synchronization (bkp_license sync) and then synchronize with the site server named. A site server only serves machines the license server names to it in a signed member list; every machine logs on with its installation certificate. The interfaces are described in docs/site-api.txt.

22.1 What the machines show of it#

bkp_license status names the site server, and while a move is running also its progress:

Output:

Own targets:      'nas.example.lan' as sink 'nas.example.lan': takes 640 GB, no quota.
Site server:      I-0000105 (https://site.example.lan:8472)
                  A move to this server is running: 2 of 3 machines moved.
                  Last sync: 2026-11-03T09:14:02+01:00.

With the hosted site server it says hosted (https://site.aegisgrid.de). The management console shows a line “Site server” in its header if a server of your own or a partner server is responsible, a move is running or the synchronization fails; the target console always shows the site server in the tab “Releases”. If a job scheduler does not reach the site server for 24 hours, it sends a mail, and a second one as soon as it works again.

22.2 A site server of your own#

22.2.1 Requirements#

• A Linux or Windows machine in your own network that runs all the time. The site server needs little: a small SQLite database, hardly any computing time.
• A name and/or an address by which all machines of the account reach it, e.g. site.example.lan, and port 8472/tcp in the firewall (Windows: the setup creates the rule; Linux: open it by hand).
• An activation code of the account with a free place. The site server takes 1 point.
• For backup and monitoring a connection to the license server (lizenz.aegisgrid.de) and to the hosted site server (site.aegisgrid.de), both over HTTPS. Without this connection see “Isolated network”.

22.2.2 Installing and activating#

The component is called site (“Site server”). The setup creates the configuration (/etc/bkp/bkp_sitesrv.cfg or %ProgramData%\AegisGrid\bkp_sitesrv.cfg, template packaging/bkp_sitesrv.cfg.example), the data folder (/var/lib/bkp_sitesrv or %ProgramData%\AegisGrid\site) and the service aegisgrid-site. The service is only started once the server is activated.

Linux: add the component and activate (Windows: choose “Site server” in the setup, then the same activate as administrator)

bkp_setup --modify --components core,site
bkp_sitesrv activate --code <activation code> --name site.example.lan --ip 192.168.10.5

--name and --ip are the names and addresses by which the machines reach the server; its server certificate is issued for them (several --name and --ip are possible). The activation shows the recovery key once:

Output:

This installation is activated (I-0000105, Example Ltd).

Recovery key of this site server (shown only this once):

    1SMR-A2E2-DQ93-9HZ2-HNAV-A4WE

Please write it down or print it and keep it in a safe place, apart from this server. The daily backups of this server are
encrypted with it; only with it can they be restored on a new server ('bkp_sitesrv restore --recovery-key ...'). AegisGrid
cannot read the backups and cannot recover the key.

The account is served by another site server so far; this one is noted as its successor. Next step: start the server
('bkp_sitesrv serve' or the service) and take the data over with 'bkp_sitesrv adopt'.

Then start the service: systemctl start aegisgrid-site (Linux) or the service “AegisGrid site server” (Windows). If the account already has another site server of its own that is to be replaced, --takeover belongs to the activation (see “Moving to new hardware”).

22.2.3 Taking over the account#

So far the hosted site server serves the account. adopt fetches its data and switches the assignment:

bkp_sitesrv adopt

Output:

The account A-000042 moves to this site server: 1 targets, 1 shares and 0 released schedulers taken over from I-0000001. The
machines switch at their next sync (at the latest within an hour); until then the old site server keeps serving them.

The machines switch at their next synchronization. What a machine still reports to the old server in the meantime is mirrored by the new one every 5 minutes. migrate-status shows who has already switched:

bkp_sitesrv migrate-status

Output:

Move of the account A-000042 to this site server
  from:           I-0000001 (hosted site server)
  state:          running
  started:        2026-11-03T09:12:40+01:00
  mirror:         not yet (every 5 minutes while the server runs)
  machines:       2 of 3 switched

I-0000102  nas (target, sched)
  state:          switched
  old server:     2026-11-03T08:59:31+01:00
  this server:    2026-11-03T09:14:02+01:00

I-0000103  office-pc1 (sched)
  state:          switched
  old server:     2026-11-03T09:02:17+01:00
  this server:    2026-11-03T09:13:55+01:00

I-0000104  laptop-7 (sched)
  state:          waiting
  old server:     2026-11-03T09:05:48+01:00
  this server:    -

The waiting machines switch at their next sync, at the latest within an hour while they are running.

Once all machines have switched, the server finishes the move itself: the old site server deletes the data of the account and confirms this with a signed deletion proof, which is put in the data folder. If a machine is away for longer (laptop on holiday), migrate-finish --force finishes anyway; it gets the new assignment as soon as it is back:

bkp_sitesrv migrate-finish --force

Output:

1 machine of the account A-000042 has not switched to this site server yet:
  I-0000104  laptop-7  waiting, last seen at the old server: 2026-11-03T09:05:48+01:00
They get the new assignment later from the license server or from the old site server, which then only hands out the
assignment for this account.
The move of the account A-000042 is finished. The old site server I-0000001 deleted its data (1 shares, 0 released
schedulers, 0 sealed packages, 1 endpoints) and confirmed that with a signed deletion proof.
Deletion proof: /var/lib/bkp_sitesrv/deletion-proof-A-000042-20261103-091822.json (check it with 'bkp_sitesrv proof <file>').
1 machine had not switched yet; it gets the new assignment from the license server at its next sync.

Without --force migrate-finish refuses as long as machines are waiting, and names the next step; with --yes there is no question. bkp_sitesrv proof <file> checks a deletion proof (signature, certificate, evidence chain):

Output:

The deletion proof is valid: signed by the site server I-0000001 (account A-000001) with a certificate of the AegisGrid install CA.
  account:        A-000042
  moved to:       I-0000105
  deleted:        2026-11-03T09:18:22+01:00
  targets:        1
  shares:         1
  keys:           3
  released schedulers: 0
  sealed packages: 0
  endpoints:      1
  machines:       3
  last export:    SHA-256 6087591aa3c3f5dc6f8e508b2302e1c8b26355bd3e9e254985adce1f59d3daeb
  evidence chain: entry 1, b24eac6f7c632cd9c9b4a925b66116b63c368f728bde57119abc3aaa86acf2bb

bkp_sitesrv migrate-abort aborts a running move: the account stays with the old site server, and it gets back everything the machines have reported to the new one in the meantime.

22.2.4 Looking at the state#

bkp_sitesrv status

Output:

Site server:      I-0000105, A-000042
Mode:             own (one account)
Listens on:       0.0.0.0:8472
Member list:      current
  issued:         2026-11-03T09:00:12+01:00
  valid until:    2026-12-03T09:00:12+01:00
  last fetched:   2026-11-03T09:00:12+01:00
  accounts:       1, active installations: 4
Revocation list:  2026-11-03T09:00:12+01:00
Clients:          3
Endpoints:        1
Backup:           daily at 02:30, at the hosted site server
  last backup:    2026-11-04T02:41:07+01:00
  next backup:    2026-11-05T02:54:58+01:00

Clients are the machines that synchronize with the server, endpoints the targets and released schedulers reported. The server fetches the member list hourly from the license server, a freshly activated machine at once; status --json prints the same in machine-readable form.

22.2.5 Backup and total failure#

The server backs up its database daily at 02:30 local time (with a random delay of up to 30 minutes), encrypted with the recovery key, to the hosted site server; 7 daily and 4 weekly backups are kept there. backup-dir in the configuration also puts them into a folder (e.g. a network drive). bkp_sitesrv backup backs up at once:

Output:

Backup made (169 KiB): kept at the hosted site server.

If the server fails completely, a new one is activated that replaces the old one at once, and the last backup is brought back:

bkp_sitesrv activate --code <activation code> --name site.example.lan --ip 192.168.10.5 --replace --yes
bkp_sitesrv restore --recovery-key 1SMR-A2E2-DQ93-9HZ2-HNAV-A4WE --yes
systemctl start aegisgrid-site

Output:

This installation is activated (I-0000107, Example Ltd).
The old site server is deactivated; this one serves the account now. Next step: bring back its last backup with
'bkp_sitesrv restore --recovery-key <key>' (the recovery key of the old site server), then start the server
('bkp_sitesrv serve' or the service).

Output:

Backup of the site server I-0000105 (account A-000042) from 2026-11-04T02:41:07+01:00.
Restored: the state of I-0000105 from 2026-11-04T02:41:07+01:00. The previous database is kept as
/var/lib/bkp_sitesrv/site.db.before-restore. Next step: start the server ('bkp_sitesrv serve' or the service); the
machines of the account sync with it from their next sync on.

• The machines need do nothing: at the next synchronization they get the new assignment and then synchronize with the new server.
• restore takes the recovery key of the backup, that is the one of the old server; it stays valid afterwards. --from-file <file> takes a backup from backup-dir. Stop the server before restore.
• The backup is at most one day old. The machines report their own targets and released schedulers at every synchronization; what was added after it is back after the next synchronization this way.

22.2.6 Moving to new hardware#

If the old server of your own is still running, the account moves without interruption: activate the new one with --takeover, start it and take over. The move finishes itself as soon as all machines have switched; after that the old server is deactivated and no longer costs a point.

bkp_sitesrv activate --code <activation code> --name site2.example.lan --takeover
systemctl start aegisgrid-site
bkp_sitesrv adopt

22.2.7 Back to the hosted site server#

bkp_sitesrv migrate-to hosted

Output:

The move of the account A-000042 back to the hosted site server is requested. The hosted site server takes the data over
within an hour; the machines then switch at their next sync, until then this site server keeps serving them.
'bkp_sitesrv status' shows the progress.
As soon as all machines have switched, this site server is deactivated; its point is no longer charged.

22.3 Isolated network#

A site server with offline = yes never tries to reach the license server. It is activated once with a connection; after that a bundle that comes into the network as a file keeps it running: the member list (valid for 90 days), the revocation list and, if its server certificate ends within 120 days, a new one. The bundle is available in the customer portal or from AegisGrid; it is imported with bundle-import:

bkp_sitesrv bundle-import /media/usb/bundle.json

Output:

Bundle imported: the member list is valid until 2027-02-01T09:30:04+01:00.

• The running server takes over the bundle within a minute; a new server certificate opens the port anew. status shows the bundle and warns 14 days before it expires.
• An isolated server mails by itself if [mail] is in the configuration (template in bkp_sitesrv.cfg.example): bundle ends in 14 days or has expired, backup failed and fine again, move by file waiting. bkp_sitesrv mails lists these mails.
• The backup only goes into backup-dir; without backup-dir status shows “Backup: no destination”.
• Virus signatures for the targets (virus check, pruef-virus): virus-db-dir = names the folder the operator fills with the ClamAV databases; targets with virus-db-source=site fetch new files from it (chapter “Check restore”, section “Checking for viruses”).
• The machines in the network get their assignment as a file: bkp_sitesrv assignment --file <file> on the server, then bkp_license site-import <file> on every machine or bkp_setup --site-assignment <file> at installation.

Moving into the isolated network (so far the hosted site server serves the account):

1. Activate the new server with a connection, then write offline = yes into the configuration and restart the service.
2. Get the export of the account from the old server (for the hosted site server from AegisGrid: bkp_sitesrv export --account <account> --file move.json) and run bkp_sitesrv adopt --from-file move.json on the new server. The export contains the account's own shares; delete it after the move.
3. Request the bundle with takeover (in the customer portal) and import it with bundle-import. From now on the account is assigned to the new server.
4. bkp_sitesrv assignment --file assignment.json and on every machine bkp_license site-import assignment.json.
5. The old server deletes the data with drop --account <account> --to <new server> --file <file> and writes a deletion proof; copy it to the new server and finish there with bkp_sitesrv migrate-finish --account <account> --proof-file <file>.

adopt --from-file on the new server names the next steps

Taken over from the file: 1 targets, 1 shares, 0 released schedulers of the account A-000042. Next steps: the bundle with the
takeover from the customer portal and 'bkp_sitesrv bundle-import' here; then 'bkp_sitesrv assignment --file <file>' for the
machines ('bkp_license site-import <file>' there) and 'bkp_sitesrv drop' on the old site server.

bkp_license site-import on a machine

The assignment is taken: this installation uses the site server I-0000111 (https://site.example.lan:8472) from the next sync on.

Moving out works the same way, only the other way round: export --file on the isolated server, adopt --from-file on the new one, drop --account <account> --to <new server> on the old one and migrate-finish --proof-file <file> on the new one.

22.4 Site server for partners#

A partner can serve the customers of their subtree on a site server of their own. Partner accounts have no activation codes and no subscription; the server therefore runs in a site account: a customer account directly below the partner that is marked as a site account in the customer portal (at most one per partner). The server's point is billed through this account and so ends up with the partner.

After marking it as the site account

The account A-000077 hosts the site server of the partner A-000017: activate bkp_sitesrv there (mode = shared); it takes over
customers of the partner with 'bkp_sitesrv adopt --account <account>'.

1. Install the component site and set mode = shared in bkp_sitesrv.cfg.
2. Activate with an activation code of the site account (bkp_sitesrv activate --code … --name site.partner.example) and start the service. The recovery key applies as with your own server; the backups are kept at the hosted site server.
3. Take over every customer one by one: bkp_sitesrv adopt --account <account>. The license server checks that the account lies below the partner. Finishing as with your own server, with --account for migrate-status, migrate-finish and migrate-abort.

bkp_sitesrv adopt --account A-000123
bkp_sitesrv migrate-status --account A-000123

Output:

The account A-000123 moves to this site server: 2 targets, 2 shares and 1 released schedulers taken over from I-0000001. The
machines switch at their next sync (at the latest within an hour); until then the old site server keeps serving them.

• status shows “Mode: shared (several accounts)” and the number of accounts. Customers not taken over stay with the hosted site server.
• A customer of the partner can get a site server of their own later; then the partner server is the old server of the move.
• The site account can only be switched off as long as the server no longer serves any customers.

22.5 Monitoring and administration API#

The license server monitors own and partner servers. It mails the technical contacts of the account if a site server has not reported for 24 hours, no backup has succeeded for 3 days, a move has not been finished after 7 days or machines cannot reach the site server, each with an all-clear when things are fine again. After a move a mail with the deletion proof follows.

For monitoring of your own the site server has an administration API on the same port under /admin/v1/ (status, clients, endpoints, backups, migrate; details in docs/site-api.txt). A token for reading:

bkp_sitesrv api-token add monitoring --role read

Output:

Token 'monitoring' (read) added. It is shown only now; please keep it safe:

    monitoring.ebb-TDLFbbB9rJR3Mj9pntjZSD3F1A43Z5JaCMKNZGQ

Send it as 'Authorization: Bearer monitoring.<secret>', or sign the requests (docs/site-api.txt).

State as JSON; the server certificate comes from the AegisGrid install CA

curl --cacert /var/lib/bkp_license/install-ca.crt \
     -H "Authorization: Bearer monitoring.ebb-TDLFbbB9rJR3Mj9pntjZSD3F1A43Z5JaCMKNZGQ" \
     https://site.example.lan:8472/admin/v1/status

read tokens may only read. admin tokens (--role admin) may also take over, abort and finish moves, but must sign their requests. On a partner server a token with --account only applies to this account. api-token list shows the tokens, api-token remove <name> removes one.

22.6 When something is wrong#

Until a problem is solved, the machines keep working with the state synchronized last; backups and restores run undisturbed.