borgmatic-collective/borgmatic
borgmatic-collective/borgmatic
Watch
9
74
Fork
You've already forked borgmatic
 57
Code Issues 71 Pull requests 3 Releases 162 Packages 1 Activity Actions 1

Support Overriding System Hostname #1317

New issue
Closed
opened 2026-05-30 06:08:54 +00:00 by quietquark · 13 comments
quietquark commented 2026-05-30 06:08:54 +00:00
Copy link

What I'd like to do and why

Just wanted to add an upstream borgbackup request that I have open:

https://github.com/borgbackup/borg/issues/9651

(borg2 already supports this).

This simplifies some use cases with borg (as documented in the above issue).

I think it is equally useful for borgmatic to support custom hostnames when one "controller" impersonates othe machines.

May also help with some other edge cases depending on how borgmatic is used. See #1310

Other notes / implementation ideas

Borgmatic should respect an environment variable (e.g. BORGMATIC_HOSTNAME or something like this depending on what gets finalized with borg as well) and use this instead of hostname wherever relevant.

Additionally if the BORG_HOSTNAME (or equivalent env var) is NOT set, then prior to invoking borg, borgmatic should duplicate the BORGMATIC_HOSTNAME variable into BORG_HOSTNAME (or equivalent) OR explicitly invoke borg via the --hostname (or whatever final option is implemented).

It will also be useful if this field/value can be used by hooks/scripts etc. when called via borgmatic.

NOTE: This requires borg support which as of creating this issue is still open (for 1.4.x but completed for 2.x).

### What I'd like to do and why Just wanted to add an upstream borgbackup request that I have open: https://github.com/borgbackup/borg/issues/9651 (borg2 already supports this). This simplifies some use cases with borg (as documented in the above issue). I think it is equally useful for borgmatic to support custom hostnames when one "controller" impersonates othe machines. May also help with some other edge cases depending on how borgmatic is used. See #1310 ### Other notes / implementation ideas Borgmatic should respect an environment variable (e.g. `BORGMATIC_HOSTNAME` or something like this depending on what gets finalized with borg as well) and use this instead of `hostname` wherever relevant. Additionally if the `BORG_HOSTNAME` (or equivalent env var) is NOT set, then prior to invoking borg, borgmatic should duplicate the `BORGMATIC_HOSTNAME` variable into `BORG_HOSTNAME` (or equivalent) OR explicitly invoke borg via the `--hostname` (or whatever final option is implemented). It will also be useful if this field/value can be used by hooks/scripts etc. when called via borgmatic. NOTE: This requires `borg` support which as of creating this issue is still open (for 1.4.x but completed for 2.x).
witten commented 2026-06-15 20:51:21 +00:00
Owner
Copy link

Seems handy. This is implemented now in main via --archive-hostname and an archive_hostname option as well. I didn't go with --hostname/hostname because that would collide with the database flags/options. Tested with Borg 2.x, but let me know if the 1.4.5 feature ends up not using a Borg flag named --hostname (which is what borgmatic passes in).

If any environment variable is used, borgmatic doesn't touch it, and it'll get passed through to Borg directly.

Seems handy. This is implemented now in main via `--archive-hostname` and an `archive_hostname` option as well. I didn't go with `--hostname`/`hostname` because that would collide with the database flags/options. Tested with Borg 2.x, but let me know if the 1.4.5 feature ends up not using a Borg flag named `--hostname` (which is what borgmatic passes in). If any environment variable is used, borgmatic doesn't touch it, and it'll get passed through to Borg directly.
quietquark commented 2026-06-16 03:40:40 +00:00
Author
Copy link

This is also particularly useful for prune but it looks like this is currently only implemented for create.

I think in general, this option could be useful in some other scenarios as well - essentially when borgmatic is being run on a host as "proxy" for another host to perform some operations (like prune, delete, archive checks, maybe even for a spot check in some cases).

This option should replace {hostname} everywhere - not just for create.

Could you also support an environment variable override for this? This will allow config file and script reuse with simple environment overrides (and may be specially useful for container setups).

This is also particularly useful for prune but it looks like this is currently only implemented for create. I think in general, this option could be useful in some other scenarios as well - essentially when borgmatic is being run on a host as "proxy" for another host to perform some operations (like prune, delete, archive checks, maybe even for a spot check in some cases). This option should replace `{hostname}` _everywhere_ - not just for create. Could you also support an environment variable override for this? This will allow config file and script reuse with simple environment overrides (and may be specially useful for container setups).
witten commented 2026-06-16 21:39:57 +00:00
Owner
Copy link

Oh, good catch. I'll have a look at the other actions.

And I think I'd prefer not to add a one-off environment variable for this one option, but (at the risk of vast overengineering) I'd be happy to look at making all borgmatic options available as environment variables in the same way that all options are now available as command-line flags. Maybe as a separate ticket?

I will say that if Borg exposes this as an environment variable, then borgmatic shouldn't have to do anything to support that.

Oh, good catch. I'll have a look at the other actions. And I think I'd prefer not to add a one-off environment variable for this one option, but (at the risk of vast overengineering) I'd be happy to look at making all borgmatic options available as environment variables in the same way that all options are now available as command-line flags. Maybe as a separate ticket? I will say that if *Borg* exposes this as an environment variable, then borgmatic shouldn't have to do anything to support that.
quietquark commented 2026-06-17 04:07:14 +00:00
Author
Copy link

@witten wrote in #1317 (comment):

And I think I'd prefer not to add a one-off environment variable for this one option, but (at the risk of vast overengineering) I'd be happy to look at making all borgmatic options available as environment variables in the same way that all options are now available as command-line flags. Maybe as a separate ticket?

(IMHO) definitely overkill and I don't think it is needed for now.

I will say that if Borg exposes this as an environment variable, then borgmatic shouldn't have to do anything to support that.

Agreed - that will allow borgmatic to be pretty much a full "pass through" wrapper for borg (probably eliminating the need to use the --archive-hostname via borgmatic for most scenarios if one goes with the environment variable option).

@witten wrote in https://projects.torsion.org/borgmatic-collective/borgmatic/issues/1317#issuecomment-14222: > And I think I'd prefer not to add a one-off environment variable for this one option, but (at the risk of vast overengineering) I'd be happy to look at making all borgmatic options available as environment variables in the same way that all options are now available as command-line flags. Maybe as a separate ticket? (IMHO) definitely overkill and I don't think it is needed for now. > I will say that if _Borg_ exposes this as an environment variable, then borgmatic shouldn't have to do anything to support that. Agreed - that will allow borgmatic to be pretty much a full "pass through" wrapper for borg (probably eliminating the need to use the `--archive-hostname` via borgmatic for most scenarios if one goes with the environment variable option).
witten commented 2026-06-17 21:59:08 +00:00
Owner
Copy link

Done! (Again.)

Done! (Again.)
🎉 1
quietquark commented 2026-06-29 05:11:20 +00:00
Author
Copy link

@witten - just a heads up that https://github.com/borgbackup/borg/issues/9651 is still work in progress but with an ongoing debate on whether to make the hostname override purely ENV VAR based or also support cmd line flags (for which you've added support).

I will update this issue once the final decision has been taken. Depending on the outcome there maybe changes and/or a rollback on the options required.

Sorry for the extra work in case that happens.

@witten - just a heads up that https://github.com/borgbackup/borg/issues/9651 is still work in progress but with an ongoing debate on whether to make the hostname override purely ENV VAR based or also support cmd line flags (for which you've added support). I will update this issue once the final decision has been taken. Depending on the outcome there maybe changes and/or a rollback on the options required. Sorry for the extra work in case that happens.
witten commented 2026-06-29 17:52:36 +00:00
Owner
Copy link

Thanks for the heads up. I'll reopen this ticket for now!

Thanks for the heads up. I'll reopen this ticket for now!
👍 1
witten reopened this issue 2026-06-29 17:52:36 +00:00
quietquark commented 2026-07-06 04:39:22 +00:00
Author
Copy link

@witten - for now there is no plan to implement command line args/options for the hostname and username overrides in borg. As a result, the only way to override hostname/username is via environment variables.

I assume that for borgmatic most of these place holders are pass through to borg and so borgmatic shouldn't care. In case there are scenarios where borgmatic needs to use a custom hostname (maybe for a spotcheck?), it would be best if borgmatic also uses the the BORG_HOSTNAME (and BORG_USERNAME) override environment variables (rather than using/expecting a separate borgmatic specific variable).

@witten - for now there is no plan to implement command line args/options for the hostname and username overrides in borg. As a result, the only way to override hostname/username is via environment variables. I assume that for borgmatic most of these place holders are pass through to borg and so borgmatic shouldn't care. In case there are scenarios where borgmatic needs to use a custom hostname (maybe for a spotcheck?), it would be best if borgmatic also uses the the BORG_HOSTNAME (and BORG_USERNAME) override environment variables (rather than using/expecting a separate borgmatic specific variable).
quietquark commented 2026-07-20 06:56:55 +00:00
Author
Copy link

@witten - Borg 1.4.5 has been released. Only environment variable support to override hostname and username (via BORG_HOSTNAME and BORG_USERNAME).

Could you please make appropriate changes in borgmatic for this (if required)?

@witten - Borg 1.4.5 has been released. Only environment variable support to override hostname and username (via BORG_HOSTNAME and BORG_USERNAME). Could you please make appropriate changes in borgmatic for this (if required)?
witten commented 2026-07-21 02:05:12 +00:00
Owner
Copy link

Thanks for the update. This feature now passes the archive_hostname option (or --archive-hostname flag) to Borg via environment variable. It also passes BORG_HOSTNAME through to Borg if archive_hostname is not set and the environment variable is. It does not however read BORG_HOSTNAME as input to borgmatic's own config. I'd be happy to implement a general mechanism for making all borgmatic config settable via environment variable (in a separate ticket), but I'd rather not implement a one-off for that.

I also added a corresponding archive_username option / --archive-username flag for the {user} placeholder.

All of this will be part of the next release.

Thanks for the update. This feature now passes the `archive_hostname` option (or `--archive-hostname` flag) to Borg via environment variable. It also passes `BORG_HOSTNAME` through to Borg if `archive_hostname` is not set and the environment variable is. It does not however read `BORG_HOSTNAME` as input to borgmatic's own config. I'd be happy to implement a general mechanism for making all borgmatic config settable via environment variable (in a separate ticket), but I'd rather not implement a one-off for that. I also added a corresponding `archive_username` option / `--archive-username` flag for the `{user}` placeholder. All of this will be part of the next release.
👍 1
quietquark commented 2026-07-21 05:18:13 +00:00
Author
Copy link

Couple of points:

  1. In borgmatic/config/schema.yaml it would be more appropriate to have example: borgmatic_user or example: backup_user instead of example: example.org for the archive_username section.
  2. Is it accurate to say that borgmatic itself doesn't use {username} or {hostname} internally - both are place holders purely for borg and as long as the BORG_HOSTNAME and BORG_USERNAME environment variables are set, borg should behave correctly in case of overrides?
Couple of points: 1. In `borgmatic/config/schema.yaml` it would be more appropriate to have `example: borgmatic_user` or `example: backup_user` instead of `example: example.org` for the `archive_username` section. 2. Is it accurate to say that borgmatic itself doesn't use `{username}` or `{hostname}` internally - both are place holders purely for borg and as long as the `BORG_HOSTNAME` and `BORG_USERNAME` environment variables are set, borg should behave correctly in case of overrides?
witten commented 2026-07-21 06:07:50 +00:00
Owner
Copy link

@quietquark wrote in #1317 (comment):

Couple of points:

1. In `borgmatic/config/schema.yaml` it would be more appropriate to have `example: borgmatic_user` or `example: backup_user` instead of `example: example.org` for the `archive_username` section.

Thanks, fixed!

2. Is it accurate to say that borgmatic itself doesn't use `{username}` or `{hostname}` internally - both are place holders purely for borg and as long as the `BORG_HOSTNAME` and `BORG_USERNAME` environment variables are set, borg should behave correctly in case of overrides?

Yes—unless you create constants with those names.

@quietquark wrote in https://projects.torsion.org/borgmatic-collective/borgmatic/issues/1317#issuecomment-14309: > Couple of points: > > 1. In `borgmatic/config/schema.yaml` it would be more appropriate to have `example: borgmatic_user` or `example: backup_user` instead of `example: example.org` for the `archive_username` section. Thanks, fixed! > 2. Is it accurate to say that borgmatic itself doesn't use `{username}` or `{hostname}` internally - both are place holders purely for borg and as long as the `BORG_HOSTNAME` and `BORG_USERNAME` environment variables are set, borg should behave correctly in case of overrides? Yes—unless you create [constants](https://torsion.org/borgmatic/reference/configuration/constants/) with those names.
👍 1
witten commented 2026-08-14 20:18:27 +00:00
Owner
Copy link

Released in borgmatic 2.1.7!

Released in borgmatic 2.1.7!
Sign in to join this conversation.
No Branch/Tag specified
Branches Tags
main
parallel-borgmatic
command-hook-steps
2.1.7
2.1.6
2.1.5
2.1.4
2.1.3
2.1.2
2.1.1
2.1.0
2.0.13
2.0.12
2.0.11
2.0.10
2.0.9
2.0.8
2.0.7
2.0.6
2.0.5
2.0.4
2.0.3
2.0.2
2.0.1
2.0.0
1.9.14
1.9.13
1.9.12
1.9.11
1.9.10
1.9.9
1.9.8
1.9.7
1.9.6
1.9.5
1.9.4
1.9.3
1.9.2
1.9.1
1.9.0
1.8.14
1.8.13
1.8.12
1.8.11
1.8.10
1.8.9
1.8.8
1.8.7
1.8.6
1.8.5
1.8.4
1.8.3
1.8.2
1.8.1
1.8.0
1.7.15
1.7.14
1.7.13
1.7.12
1.7.11
1.7.10
1.7.9
1.7.8
1.7.7
1.7.6
1.7.5
1.7.4
1.7.3
1.7.2
1.7.1
1.7.0
1.6.6
1.6.5
1.6.4
1.6.3
1.6.2
1.6.1
1.6.0
1.5.24
1.5.23
1.5.22
1.5.21
1.5.20
1.5.19
1.5.18
1.5.17
1.5.16
1.5.15
1.5.14
1.5.13
1.5.12
1.5.11
1.5.10
1.5.9
1.5.8
1.5.7
1.5.7.dev0
1.5.6
1.5.5
1.5.4
1.5.3
1.5.2
1.5.1
1.5.0
1.4.22
1.4.21
1.4.20
1.4.19
1.4.18
1.4.17
1.4.16
1.4.15
1.4.14
1.4.13
1.4.12
1.4.11
1.4.10
1.4.9
1.4.8
1.4.7
1.4.6
1.4.5
1.4.4
1.4.3
1.4.2
1.4.1
1.4.0
1.3.26
1.3.25
1.3.24
1.3.23
1.3.22
1.3.21
1.3.20
1.3.19
1.3.18
1.3.17
1.3.16
1.3.15
1.3.14
1.3.13
1.3.12
1.3.11
1.3.10
1.3.9
1.3.8
1.3.7
1.3.6
1.3.5
1.3.4
1.3.3
1.3.2
1.3.1
1.3.0
1.2.18
1.2.17
1.2.16
1.2.15
1.2.14
1.2.13
1.2.12
1.2.11
1.2.10
1.2.9
1.2.8
1.2.7
1.2.6
1.2.5
1.2.4
1.2.3
1.2.2
1.2.1
1.2.0
1.1.15
1.1.14
1.1.13
1.1.12
1.1.11
1.1.10
1.1.9
1.1.7
1.1.6
1.1.5
1.1.4
1.1.3
1.1.2
1.1.1
1.1.0
1.0.3
1.0.2
1.0.1
1.0.0
0.1.8
0.1.7
0.1.6
0.1.5
0.1.4
0.1.3
0.1.2
0.1.1
0.1.0
0.0.7
0.0.6
0.0.5
0.0.4
0.0.3
0.0.2
Labels
Clear labels   
blocked

   
breaking

   
bug

   
data loss

   
design finalized

   
good first issue

   
new feature area

   
question / support

   
security

   
waiting for response
No labels
blocked
breaking
bug
data loss
design finalized
good first issue
new feature area
question / support
security
waiting for response
Milestone
Clear milestone
No items
No milestone
Assignees
Clear assignees
No assignees
2 participants
Notifications
Due date
The due date is invalid or out of range. Please use the format "yyyy-mm-dd".

No due date set.

Dependencies

No dependencies set

Reference
borgmatic-collective/borgmatic#1317
No description provided.