Guide: Updated Automating Backups on StartOS 0.4.0 (Advanced)

Guides
1

The guide below is a new draft updating the earlier guide for automating backups. This is more advanced and more complicated because it provides more protection for your password. Feedback is greatly appreciated.

Automating StartOS Backups with SSH and Cron

This guide applies to StartOS 0.4.0. It is fully standalone: it does not
install, require, or reference any third-party administration tool. Every
step uses only what StartOS itself ships (SSH, start-cli, and cron) plus
a root-only password file this guide has you create.

[!WARNING]
This is an advanced administrative procedure. It changes StartOS’s persistent
host configuration and requires a restart. Follow the commands exactly,
substitute only the clearly marked placeholders, and test a backup before
relying on the schedule.

[!IMPORTANT]
Backups are encrypted with the StartOS primary password that was active when
they were made. Keep that password in a secure password manager. Changing the
StartOS password does not re-encrypt existing backups.

[!CAUTION]
Use this guide at your own risk. It is accurate to the best of the
author’s knowledge at the time of writing, but StartOS, start-cli, and
cron can all change, and this guide can be wrong, incomplete, or out of date
by the time you follow it. It is your responsibility, not the author’s,
to read, understand, and validate every command below before you run it,
including confirming what each command actually does on your own server.
Test with non-critical data first. Running commands as root on your own
server, on a schedule, unattended, carries real risk of data loss or a
broken system if a step is skipped, mistyped, or misunderstood. The author
provides this guide as-is, assumes no responsibility for how you use it, and
accepts no liability for data loss, downtime, a failed or unrecoverable
backup, or any other consequence of following it, applying it incorrectly,
or relying on it, including consequences of an error in the guide itself.

What this guide does

The procedure:

  1. Confirms that a backup target works through the StartOS web interface.
  2. Identifies that target’s ID with start-cli.
  3. Stores the encryption password in a root-only file rather than in the
    crontab or shell history.
  4. Creates a root-only wrapper script that starts the backup.
  5. Uses root’s crontab to run that script on a chosen schedule.
  6. Makes the configuration persistent in one StartOS restart.

The schedule can back up every installed service or a selected list. Backups
briefly stop every selected service that was running, then StartOS restarts it
when that service’s backup is done. Plan the schedule for a time when that
downtime is acceptable.

Why a password file and wrapper script, instead of one crontab line

The simplest version of this schedule is a single crontab line that calls
start-cli backup create <target-id> <password> directly. Avoid that
approach: the password would then appear in plain text in crontab -l, in
/var/spool/cron/crontabs/root, and in any output file the job’s log is
redirected to, readable by anyone who can read your crontab or that log,
not just root running the backup.

This guide instead writes the password once to a root-only file (chmod 600)
and has a wrapper script read that file at run time. The crontab entry then
only ever names the wrapper script, never the password itself. The one
remaining exposure (start-cli briefly shows the password in the process
list while a backup runs, because the CLI currently takes it as a command
argument) is unavoidable with the current start-cli syntax and is called
out again at the step where it applies.

Before you begin

You need:

  • A StartOS 0.4.0 server.
  • SSH access as the start9 user and its normal sudo access. SSH is enabled
    by default on every StartOS server; see Start9’s
    SSH guide
    for connection details.
  • A backup target already configured in StartOS: a supported physical drive or
    a network folder.
  • The StartOS primary password that will encrypt new backups.
  • Enough free space on the target for the data you intend to back up.

For valuable data, maintain current backups on more than one target. StartOS
updates the backup on a given target; multiple targets provide independent
recovery copies.

[!IMPORTANT]
Backup target must be available when backups run.

The backup target must actually be available at the moment each scheduled
backup runs, or that backup will fail. A network-folder target must be
powered on, reachable on the network, and shared under the same path and
credentials StartOS already has configured for it. A removable-drive target
must be physically connected to the server at that time. Check the StartOS
notification panel after every scheduled run. Cron reporting that it
started the job is not proof that the backup itself succeeded.

1. Create and test a manual backup

Before automating anything, open System → Create Backup in the StartOS web
interface.

  1. Add or select a physical-drive or network-folder target.
  2. Confirm the target has enough available space.
  3. Start a manual backup and wait for its completion report.
  4. Resolve every unexpected service failure in that report.
  5. Save the password used to encrypt the backup in a secure password manager.

StartOS writes current backups to StartOSBackupsV2. If the target contains
an older StartOSBackups (V1) backup for this server, read the UI warning
before selecting Delete old backup. Do not remove the old backup until a
current-format backup is known to exist on that target.

2. Find the backup target ID

SSH to the server from your computer:

ssh start9@<server-ip-or-hostname>

List the configured backup targets:

start-cli backup target list

Find the target you tested in the web interface. Its ID is the first value on
its entry. A network-folder target looks like cifs-6; a directly attached
disk (a USB drive or other physical media) looks like disk-/dev/sda1,
/ included. Record it exactly as shown, / included, as <target-id> for
the remaining steps. Do not guess the ID or copy an ID for a different
target.

[!NOTE]
A disk target’s ID contains a /, which is not valid inside a file name.
Step 4 below shows how to derive a filesystem-safe version of it for use in
file paths. Use <target-id> exactly as recorded here everywhere else,
including as the argument to start-cli.

3. Enter StartOS persistence mode

By default, ordinary host changes do not survive a StartOS reboot. Enter
persistence mode before creating the password file, script, or cron entry:

sudo /usr/lib/startos/scripts/chroot-and-upgrade

You are now in the persistent root environment. Do not run exit until the
configuration steps below (through adding the cron entry) are complete.
Exiting this environment causes StartOS to restart. The wrapper is tested
afterward, not before, since start-cli cannot reach the RPC daemon from
inside this environment.

4. Create a root-only password file

This keeps the StartOS password out of the crontab and out of the command you
will schedule.

File names cannot contain /, but a disk target’s ID does (for example
disk-/dev/sda1). Before naming the password file, derive a
filesystem-safe version of <target-id> by replacing every / with _.
A network-folder ID like cifs-6 has no / and is unaffected;
disk-/dev/sda1 becomes disk-_dev_sda1. Call this value
<safe-target-id>; it is used only in file paths below. Continue to use
the original <target-id>, / included, everywhere it is passed to
start-cli or assigned to a script’s TARGET_ID variable.

Replace <safe-target-id> below with the value you just derived:

install -d -m 700 /root/.startos-backup
read -rsp "StartOS primary password: " BACKUP_PASSWORD
printf '\n'
printf '%s' "$BACKUP_PASSWORD" > /root/.startos-backup/<safe-target-id>.password
unset BACKUP_PASSWORD
chmod 600 /root/.startos-backup/<safe-target-id>.password

The password prompt does not echo what you type. Confirm that the file exists
and has the expected root-only permissions, without printing its contents:

ls -l /root/.startos-backup/<safe-target-id>.password

The output should show a file owned by root with permissions -rw-------.

[!WARNING]
The start-cli backup create command currently requires the password as an
argument. The wrapper in the next step therefore exposes it briefly to a
privileged process listing while a backup runs. Do not grant SSH or root
access to untrusted administrators.

5. Create the scheduled-backup wrapper

Create and edit a root-only script:

nano /usr/local/sbin/startos-scheduled-backup

Paste the following content, then replace <target-id> with the value from
step 2 (/ included) and <safe-target-id> with the filesystem-safe version
you derived in step 4. Keep the surrounding quotes exactly as shown.

#!/bin/sh
set -eu

TARGET_ID='<target-id>'
PASSWORD_FILE='/root/.startos-backup/<safe-target-id>.password'
LOG_FILE='/root/.startos-backup/scheduled-backup.log'

/usr/bin/start-cli backup create "$TARGET_ID" "$(cat "$PASSWORD_FILE")" \
  >> "$LOG_FILE" 2>&1

To back up only specific services instead of all of them, use
--package-ids with comma-separated package IDs in that final command
instead:

/usr/bin/start-cli backup create "$TARGET_ID" "$(cat "$PASSWORD_FILE")" \
  --package-ids nextcloud,vaultwarden >> "$LOG_FILE" 2>&1

Leaving out --package-ids backs up all installed services.

Save in nano with Ctrl+X, then Y, then Enter. Restrict the script
to root:

chmod 700 /usr/local/sbin/startos-scheduled-backup
ls -l /usr/local/sbin/startos-scheduled-backup

The output should show a file owned by root with permissions
-rwx------, the same way step 4 confirmed the password file.

Then verify that StartOS provides start-cli at the expected path:

test -x /usr/bin/start-cli && echo "start-cli is present and executable" || echo "start-cli is missing or not executable"

Confirm you see the “present and executable” message before moving on.

[!TIP]
The cron entry will run the wrapper, not start-cli directly. This keeps the
crontab free of secrets and avoids cron’s limited command-search path.

6. Add the cron schedule

Edit root’s crontab while you are still in persistence mode:

crontab -e

If prompted to choose an editor, select nano. Add one line for the schedule
you want. This example runs every day at 03:00:

0 3 * * * /usr/local/sbin/startos-scheduled-backup

Other common five-field schedules are:

Frequency Cron expression
Every day at midnight 0 0 * * *
Every Sunday at midnight 0 0 * * 0
Weekdays at 02:00 0 2 * * 1-5
First day of the month at 22:30 30 22 1 * *

Save the crontab with Ctrl+X, then Y, then Enter. Confirm the entry
without opening the editor:

crontab -l

The listed line must contain only the wrapper path, never a password.

7. Restart to make the schedule persistent

When the crontab entry looks correct, leave persistence mode:

exit

StartOS restarts automatically and the SSH session disconnects. Wait for the
server and its services to come back online, then reconnect.

8. Test the wrapper

Reconnect over SSH now that the server has restarted:

ssh start9@<server-ip-or-hostname>

You are no longer in persistence mode, so use sudo to run the root-only
wrapper and read its log:

sudo /usr/local/sbin/startos-scheduled-backup
sudo tail -n 100 /root/.startos-backup/scheduled-backup.log

The CLI’s successful return means the backup was accepted or queued; it is not
proof that every service completed successfully. In the StartOS web interface,
wait for and inspect the backup-completion notification/report. Do not
consider the schedule verified until that report shows the expected
successful backup.

9. Verify ongoing backups

After the first scheduled time:

  1. Open the StartOS notification panel and inspect the backup-completion
    report.

  2. Review the wrapper log if the schedule did not appear to run:

    sudo tail -n 100 /root/.startos-backup/scheduled-backup.log

  3. Confirm the target still has enough free space.

  4. Periodically test restoring non-critical data so the recovery procedure is
    familiar before an emergency.

Schedule the next run far enough after the prior backup that it can finish.
The log shows whether the CLI started the job; the StartOS completion report is
the authoritative record of whether the backup succeeded.

Changing or removing the schedule

To change the target, services, password, script, or cron timing, reconnect
over SSH and enter persistence mode again:

sudo /usr/lib/startos/scripts/chroot-and-upgrade

Edit the wrapper with nano /usr/local/sbin/startos-scheduled-backup, or edit
the schedule with crontab -e. Exit persistence mode to apply the change and
let the server restart, then test the revised wrapper as in step 8.
start-cli cannot reach the RPC daemon while still inside persistence mode,
so testing it before exiting will always fail regardless of whether the
change is correct.

To stop scheduled backups, remove the wrapper line from crontab -e, then
exit persistence mode to restart. If no other scheduled backup uses the target,
remove the corresponding password file as well (using the same
<safe-target-id> from step 4):

rm /root/.startos-backup/<safe-target-id>.password

Only remove the exact password file you no longer need. A target may be used by
more than one schedule.

Restoring from a backup

For an accidentally uninstalled service, use System → Restore from Backup,
select the backup target, enter the password that encrypted that backup, select
the service, and restore it.

For loss or corruption of the StartOS data drive, use the StartOS initial-setup
recovery flow. A successful scheduled job is not a substitute for periodically
confirming that you can locate the target and the password required to restore.

Troubleshooting

Symptom Check
No scheduled backup starts Confirm the cron line with sudo crontab -l; confirm you exited persistence mode and the server restarted.
Cron ran but no successful backup report appears Check /root/.startos-backup/scheduled-backup.log, then inspect StartOS notifications for the actual backup failure.
start-cli cannot be found Confirm /usr/bin/start-cli exists with test -x /usr/bin/start-cli.
Authentication or password error Confirm the password file is for the intended target and has mode 600; after a password change, make a manual UI backup first.
A service is unavailable during the backup This is expected: StartOS stops selected running services while backing them up.

Advanced: separate daily, weekly, and monthly targets

A single target keeps only the most recent backup: StartOS overwrites it on
every run. If you want a current daily, a current weekly, and a current
monthly restore point available at the same time (so, for example, a bad
daily backup doesn’t overwrite the only copy of a service’s data), use three
separate backup targets and let ordinary cron scheduling put the right backup
on the right target. No custom scripting logic is needed; three plain cron
lines do it.

  1. In the StartOS web interface, create three backup targets. For example,
    three folders on the same network share, or three separate drives, and
    give each a name you’ll recognize, such as daily, weekly, and
    monthly. Test a manual backup to each target individually, following
    step 1 above.

  2. Run start-cli backup target list (step 2 above). You’ll now see three
    entries; record each target’s ID as <daily-target-id>,
    <weekly-target-id>, and <monthly-target-id>.

  3. While in persistence mode (step 3 above), repeat step 4 above three
    times, once per target ID to create three password files:

    • /root/.startos-backup/<daily-target-id>.password
    • /root/.startos-backup/<weekly-target-id>.password
    • /root/.startos-backup/<monthly-target-id>.password

    All three will hold the same value: one StartOS primary password encrypts
    every backup on the server, regardless of target. If any of the three
    targets is a directly attached disk, its ID contains a /; derive its
    filesystem-safe form as in step 4 above before naming that target’s
    password file.

  4. Repeat step 5 above three times to create three wrapper scripts, each
    pointed at its own target and password file:

    • /usr/local/sbin/startos-scheduled-backup-daily
    • /usr/local/sbin/startos-scheduled-backup-weekly
    • /usr/local/sbin/startos-scheduled-backup-monthly

    Give each script its own TARGET_ID and PASSWORD_FILE. A shared
    LOG_FILE (/root/.startos-backup/scheduled-backup.log) is fine for all
    three. chmod 700 each script.

  5. Add three lines to root’s crontab (step 6 above):

    # Daily target: every day except Sunday
0 3 * * 1-6 /usr/local/sbin/startos-scheduled-backup-daily

# Weekly target: Sunday only
0 3 * * 0 /usr/local/sbin/startos-scheduled-backup-weekly

# Monthly target: the 1st of every month, every day of the week
0 4 1 * * /usr/local/sbin/startos-scheduled-backup-monthly

    cron evaluates each line independently, so this needs no extra logic: on
    an ordinary day only the daily line fires; on a Sunday only the weekly
    line fires; on the 1st of the month the monthly line fires in addition
    to     whichever of the daily or weekly lines also matches that day,
    automatically giving you “everything else, plus monthly” with no
    conditional required. The monthly line starts 60 minutes after the
    daily and weekly lines (0 4 instead of 0 3) so the two backups
    never launch at the same moment on the 1st of the month. Adjust the
    hour to a time your services can tolerate downtime at, keeping that
    60-minute gap between the monthly time and the other two. cron’s
    day-of-week field treats both 0 and 7 as Sunday. This guide uses
    0.

  6. Confirm all three lines with crontab -l, then exit persistence mode
    (step 7 above) to make the schedule permanent and let the server restart.

  7. Once reconnected, test each wrapper individually (step 8 above) and
    confirm a successful completion report in the StartOS web interface for
    each of the three targets. Testing from inside persistence mode is not
    possible. start-cli cannot reach the RPC daemon there.

  8. After each target’s first scheduled run, verify it independently (step 9
    above). A healthy daily target doesn’t guarantee the weekly or monthly
    targets are also succeeding.

[!NOTE]
Each of the three targets is still overwritten on every run of its own
schedule. This gives you one current daily, one current weekly, and one
current monthly backup, not a rolling history of many. For a longer
history, add more targets and cron lines following the same pattern.

1 Like
Automated Backups