Update backup documentation for foremanctl by aneta-petrova · Pull Request #4850 · theforeman/foreman-documentation

aneta-petrova · 2026-05-18T10:23:20Z

What changes are you introducing?

Updating documentation for offline backups to use foremanctl rather than foreman-maintain.

Why are you introducing these changes? (Explanation, links to references, issues, etc.)

The foremanctl backup command will replace foreman-maintain backup.

Anything else to add? (Considerations, potential downsides, alternative solutions you have explored, etc.)

~~This PR depends on #4846, which is why I cherry-picked the changes from the other PR so that I could start the foremanctl part already.~~

Contributor checklists

I am okay with my commits getting squashed when you merge this PR.
I am familiar with the contributing guidelines.

Please cherry-pick my commits into:

Foreman 3.19/Katello 4.21
Foreman 3.18/Katello 4.20 (Satellite 6.19)
Foreman 3.17/Katello 4.19
Foreman 3.16/Katello 4.18 (Satellite 6.18; orcharhino 7.6, 7.7, and 7.8)
Foreman 3.15/Katello 4.17
Foreman 3.14/Katello 4.16 (Satellite 6.17; orcharhino 7.4; orcharhino 7.5)
Foreman 3.13/Katello 4.15 (EL9 only)
Foreman 3.12/Katello 4.14 (Satellite 6.16; orcharhino 7.2 on EL9 only; orcharhino 7.3)
We do not accept PRs for Foreman older than 3.12.

github-actions · 2026-05-19T09:49:41Z

The PR preview for 9adca92 is available at theforeman-foreman-documentation-preview-pr-4850.surge.sh

The following output files are affected by this PR:

show diff

show diff as HTML

aneta-petrova · 2026-06-23T14:46:19Z

Hi @sjha4 and @sambible, can you please review these foremanctl backup documentation updates? This PR updates only the offline backup bits, so the rest of the backup chapter has some gaps, but those should be addressed in follow-up PRs, along with code updates.

aneta-petrova · 2026-06-24T07:39:41Z

There are a few warnings related to heading/ID/filename mismatches now. I'm taking two things from that:

The check is working, yay!
I don't know how to avoid this because we need different headings for containerized and non-containerized. I'm inclined to accept this as an unfortunate side effect of the containerization work.

sjha4

Looks good! Ack.. ✔️

maximiliankolb

I don't know how to avoid this because we need different headings for containerized and non-containerized.

I really dislike this; the only solution would be to have separate modules.

I'm inclined to accept this as an unfortunate side effect of the containerization work.

Yes, I very much agree that we can/should accept this if it's a temporary issue. Is there active work on backup/restore for foremanctl? Any issue/PR that we can watch?

aneta-petrova · 2026-06-25T06:53:32Z

I don't know how to avoid this because we need different headings for containerized and non-containerized.

I really dislike this; the only solution would be to have separate modules.

I'm inclined to accept this as an unfortunate side effect of the containerization work.

Yes, I very much agree that we can/should accept this if it's a temporary issue. Is there active work on backup/restore for foremanctl? Any issue/PR that we can watch?

You know what, it might be best to have separate modules.

The expectation is that we'll be providing both containerized and non-containerized docs in upstream for a few releases, so we'd have to accept the failing check for far too long.

I'll try creating those separate modules and then ask for a style re-review.

aneta-petrova · 2026-06-25T06:56:10Z

You know what, it might be best to have separate modules.

The expectation is that we'll be providing both containerized and non-containerized docs in upstream for a few releases, so we'd have to accept the failing check for far too long.

I'll try creating those separate modules and then ask for a style re-review.

Oh wait, I spoke too soon (and early, because there's been no coffee yet): This particular check would not stay here for as long as we'll be providing non-containerized docs. It's here only until the code catches up with the old docs and foremanctl supports proxy backups. I'm not sure when that will be, though.

Still, I want to investigate whether separate modules is a viable solution anyway.

Co-authored-by: Maximilian Kolb <mail@maximilian-kolb.de>

aneta-petrova · 2026-06-25T19:36:59Z

@maximiliankolb What if I just rename all the files to refer to {Project} in their headings/IDs/filenames rather than {ProjectServer} and {SmartProxyServer}? That's what I tried. Do you think it works well enough?

maximiliankolb

One tiny suggestion; feel free to apply and merge.

Thanks Anet, style-wise LGTM.

maximiliankolb · 2026-06-26T05:55:05Z

@maximiliankolb What if I just rename all the files to refer to {Project} in their headings/IDs/filenames rather than {ProjectServer} and {SmartProxyServer}? That's what I tried. Do you think it works well enough?

Yes, I think that's a great idea.

Co-authored-by: Maximilian Kolb <mail@maximilian-kolb.de>

* Update offline backup for foremanctl * Exclude backup options that foremanctl does not support yet * foremanctl doesn't have --assumeyes --------- Co-authored-by: Maximilian Kolb <mail@maximilian-kolb.de>

pr-processor Bot added the Not yet reviewed label May 18, 2026

github-actions Bot added Needs tech review Requires a review from the technical perspective Needs style review Requires a review from docs style/grammar perspective Needs testing Requires functional testing labels May 18, 2026

aneta-petrova removed Needs tech review Requires a review from the technical perspective Needs style review Requires a review from docs style/grammar perspective Needs testing Requires functional testing labels May 18, 2026

aneta-petrova commented May 18, 2026

View reviewed changes

Comment thread guides/common/modules/con_directories-created-during-backups.adoc Outdated

pr-processor Bot removed the Not yet reviewed label May 18, 2026

aneta-petrova force-pushed the foremanctl-backup-restore branch from f90b224 to 2f9ff86 Compare May 19, 2026 09:45

aneta-petrova force-pushed the foremanctl-backup-restore branch from 2f9ff86 to 04a382e Compare May 20, 2026 08:10

aneta-petrova force-pushed the foremanctl-backup-restore branch 4 times, most recently from f410c40 to 61aa2da Compare June 23, 2026 12:54

Update offline backup for foremanctl

45bbee4

aneta-petrova force-pushed the foremanctl-backup-restore branch 2 times, most recently from f4ee8b6 to ca154d7 Compare June 23, 2026 14:19

aneta-petrova commented Jun 23, 2026

View reviewed changes

Comment thread guides/doc-Administering_Project/master.adoc Outdated

aneta-petrova marked this pull request as ready for review June 23, 2026 14:42

sjha4 reviewed Jun 23, 2026

View reviewed changes

Comment thread guides/common/modules/con_directories-created-during-backups.adoc Outdated

sjha4 reviewed Jun 23, 2026

View reviewed changes

Comment thread guides/common/modules/proc_performing-a-full-backup.adoc Outdated

aneta-petrova added 2 commits June 24, 2026 09:40

Expose backup docs in Admin

a663067

Update offline backup description with foremanctl details

ae20631

aneta-petrova force-pushed the foremanctl-backup-restore branch from b2f458a to 1fcb34a Compare June 24, 2026 07:41

Add a backup best practice

1dffeda

aneta-petrova force-pushed the foremanctl-backup-restore branch from 1fcb34a to 855b664 Compare June 24, 2026 07:42

sjha4 reviewed Jun 24, 2026

View reviewed changes

Comment thread guides/common/modules/proc_preparing-the-source-server-for-cloning.adoc Outdated

foremanctl doesn't have --assumeyes

272c043

sjha4 approved these changes Jun 24, 2026

View reviewed changes

aneta-petrova added tech review done No issues from the technical perspective Needs style review Requires a review from docs style/grammar perspective Needs testing Requires functional testing labels Jun 24, 2026

maximiliankolb requested changes Jun 25, 2026

View reviewed changes

Comment thread guides/common/modules/ref_available-backup-methods.adoc Outdated

Comment thread guides/common/modules/ref_available-backup-methods.adoc Outdated

Comment thread guides/common/modules/ref_best-practices-for-backing-up-project.adoc Outdated

pr-processor Bot added the Waiting on contributor Requires an action from the author label Jun 25, 2026

pr-processor Bot added Needs re-review and removed Waiting on contributor Requires an action from the author labels Jun 25, 2026

Update headings to refer to Project rather than server/proxy

e1e2098

aneta-petrova force-pushed the foremanctl-backup-restore branch from 65c3b0e to e1e2098 Compare June 25, 2026 19:28

Apply suggestions from code review

f02126c

Co-authored-by: Maximilian Kolb <mail@maximilian-kolb.de>

maximiliankolb approved these changes Jun 26, 2026

View reviewed changes

Comment thread guides/common/modules/proc_updating-server.adoc Outdated

Comment thread ...ring-for-disaster-recovery-with-active-and-passive-project-server-with-external-storage.adoc

pr-processor Bot removed the Needs re-review label Jun 26, 2026

maximiliankolb added style review done No issues from docs style/grammar perspective and removed Needs style review Requires a review from docs style/grammar perspective labels Jun 26, 2026

Apply suggestion from @maximiliankolb

9adca92

Co-authored-by: Maximilian Kolb <mail@maximilian-kolb.de>

maximiliankolb approved these changes Jun 26, 2026

View reviewed changes

aneta-petrova mentioned this pull request Jun 26, 2026

Expose containerized Admin guide in navigation #4983

Merged

8 tasks

sambible approved these changes Jun 26, 2026

View reviewed changes

aneta-petrova added testing done No issues from the functional perspective and removed Needs testing Requires functional testing labels Jun 30, 2026

aneta-petrova merged commit 4661bf4 into theforeman:master Jun 30, 2026
12 checks passed

aneta-petrova deleted the foremanctl-backup-restore branch June 30, 2026 07:15

Uh oh!

Conversation

aneta-petrova commented May 18, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

What changes are you introducing?

Why are you introducing these changes? (Explanation, links to references, issues, etc.)

Anything else to add? (Considerations, potential downsides, alternative solutions you have explored, etc.)

Contributor checklists

Uh oh!

Uh oh!

github-actions Bot commented May 19, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

Uh oh!

aneta-petrova commented Jun 23, 2026

Uh oh!

Uh oh!

Uh oh!

aneta-petrova commented Jun 24, 2026

Uh oh!

Uh oh!

sjha4 left a comment

Choose a reason for hiding this comment

Uh oh!

maximiliankolb left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

aneta-petrova commented Jun 25, 2026

Uh oh!

aneta-petrova commented Jun 25, 2026

Uh oh!

aneta-petrova commented Jun 25, 2026

Uh oh!

maximiliankolb left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

maximiliankolb commented Jun 26, 2026

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

4 participants

aneta-petrova commented May 18, 2026 •

edited

Loading

github-actions Bot commented May 19, 2026 •

edited

Loading