Every DevOps team has a folder of shell scripts that keep things running: deploy helpers, health checks, backups, cleanup jobs. Bash is everywhere, needs nothing installed and glues the commands you already know into repeatable steps. It also has sharp edges: an unquoted variable or an ignored error can turn a cleanup script into a deletion script. The difference between a fragile script and a trustworthy one is a handful of habits.
In this lesson you learn those habits from the start: how scripts run, how variables and quoting really work, how to react to exit codes, and how to structure a script with functions, traps and logging. Along the way you build /usr/local/bin/orbit-backup.sh, the script that lesson 15 will run every night.
Note: everything here works on the lab VM, in WSL or in a ubuntu:26.04 container. Only the final run needs the Orbit directories, which the “If you skipped ahead” block creates.
Your first script
A script is a text file of commands. The first line, the shebang, tells the kernel which interpreter runs it:
#!/usr/bin/env bash
# hello.sh: print who and where we are
echo "Hello from $(hostname), running as $(whoami)"
#!/usr/bin/env bash finds bash on the PATH; #!/bin/bash is equally fine on any Linux server. Make the file executable with chmod +x hello.sh and run it with a path, ./hello.sh, because the current directory is not on the PATH. bash hello.sh also works without the execute bit. A script that starts with #!/bin/sh runs under dash on Ubuntu, which lacks arrays, [[ ]] and other features used below, so say bash when you mean Bash.
Variables and quoting
Assign without spaces around = (data_dir="/var/lib/orbit") and read with $. Braces mark where a name ends: "${app}_backup" works, "$app_backup" looks for a variable called app_backup. Quoting decides how Bash treats the text:
| Quotes | Variables expanded? | Example | Result |
|---|---|---|---|
Double "..." | Yes, and the result stays one word | "$data_dir" | /var/lib/orbit |
Single '...' | No, everything is literal | '$data_dir' | $data_dir |
| None | Yes, then split on spaces and expanded as globs | $data_dir | Fine today, broken with spaces or * |
The rule: always quote variable expansions, "$var". Unquoted, a file called Q3 report.pdf becomes two arguments, and an empty variable vanishes entirely, so rm -rf $dir/ with an empty $dir becomes rm -rf /.
Command substitution, parameter expansion and arrays
$(command) inserts a command’s output. Parameter expansion edits a variable without calling another program. Arrays hold lists whose elements may contain spaces:
stamp=$(date +%Y%m%d-%H%M%S) # 20261103-021500
file="/var/backups/orbit/orbit-$stamp.tar.gz"
echo "${file##*/}" # orbit-20261103-021500.tar.gz (strip up to the last /)
echo "${file%.tar.gz}" # remove the suffix
echo "${KEEP:-7}" # 7 if KEEP is unset or empty
sources=(/var/lib/orbit /etc/orbit)
echo "${#sources[@]} sources" # 2 sources
for src in "${sources[@]}"; do echo "$src"; done
"${sources[@]}" (quoted, with @) expands to one word per element: it is the array version of “always quote”.
Arguments and exit codes
| Parameter | Meaning |
|---|---|
$0 | The script’s name or path |
$1, $2 … | First, second argument |
$# | Number of arguments |
"$@" | All arguments, each as a separate word (almost always what you want) |
$? | Exit code of the last command |
Every command ends with an exit code: 0 means success, 1 to 255 mean failure. Shells, cron, systemd and CI pipelines all read it, so your script must return an honest one. ls /nope; echo $? prints 2. React to codes directly rather than inspecting $? later: mkdir -p "$dest" || exit 1, or if grep -q orbit /etc/passwd; then .... End with exit 0 for success or a non-zero number for failure.
Strict mode: set -euo pipefail
Bash by default keeps going after errors. Put set -euo pipefail right after the shebang of every script:
-e(errexit): stop as soon as a command fails, instead of running the next lines on a broken state.-u(nounset): treat an unset variable as an error, so a typo like$DEST_DIRRstops the script instead of expanding to nothing.-o pipefail: a pipeline fails if any command in it fails, not only the last. Without it,tar -c ... | gzip > out.gz“succeeds” even whentarfailed.
-e has blind spots: it does not fire for commands inside an if condition or on the left of && and ||, and (( count++ )) returns failure when the old value is 0, which stops the script. Strict mode is a safety net, not a replacement for checking what matters. To debug, bash -x script.sh prints each command before running it.
Tests and conditions
[[ ... ]] is Bash’s test command. It is safer than the old [ ... ]: no word splitting inside, and it supports &&, ||, globs and regular expressions.
| Test | True when |
|---|---|
-e path / -f path / -d path | Path exists / is a regular file / is a directory |
-r path / -w path / -x path | You can read / write / execute it |
-s path | File exists and is not empty |
-z "$s" / -n "$s" | String is empty / not empty |
"$a" == "$b" / "$a" != "$b" | Strings equal / differ (right side can be a glob) |
"$s" =~ ^[0-9]+$ | String matches a regular expression |
$a -eq $b, -ne, -lt, -le, -gt, -ge | Integer comparisons; or use (( a > b )) |
if [[ ! -d "$data_dir" ]]; then
echo "missing $data_dir" >&2; exit 1
elif [[ ! -s "$data_dir/notes.json" ]]; then
echo "warning: no notes yet" >&2
fi
case "$1" in
start|stop|restart) systemctl "$1" orbit-api ;;
status) systemctl --no-pager status orbit-api ;;
*) echo "usage: $0 {start|stop|restart|status}" >&2; exit 2 ;;
esac
>&2 sends a message to standard error, where errors belong (lesson 5 covers streams). case is clearer than a chain of elif when you match one value against several patterns; *) catches everything else.
Loops
for walks a list; let the shell expand globs instead of parsing ls. while read is the correct way to process a file line by line:
for f in /var/log/orbit/*.log; do
[[ -e "$f" ]] || continue # no match: the glob stays literal
echo "$f: $(wc -l < "$f") lines"
done
while IFS=: read -r user _ uid _ _ home shell; do
if (( uid >= 1000 )); then echo "$user $home $shell"; fi
done < /etc/passwd
IFS=: splits on colons for that command only, -r keeps backslashes literal and _ collects fields you do not need. while and until also make good retry loops: until curl -fsS http://127.0.0.1:3000/ > /dev/null; do sleep 2; done.
Functions, here-docs, traps and options
Functions group steps, are defined as name() { ...; } and called like commands. Inside, $1 and $@ are the function’s own arguments, return N sets its exit code, and local dir="$1" keeps a variable from leaking into the rest of the script. Small one-line helpers such as log and die make every script easier to read, as you will see below.
A here-doc (cat <<EOF, then lines of text, then EOF) feeds a block of text to a command, ideal for usage messages and generated files; <<EOF expands variables, <<'EOF' keeps everything literal. trap runs a command when the script exits, for any reason, which makes cleanup reliable: tmp=$(mktemp) followed by trap 'rm -f "$tmp"' EXIT removes the temporary file even after an error.
For flags like -k 7, the built-in getopts parses options in a while loop: in the spec ':d:k:h', a letter followed by : takes a value (in $OPTARG), and the leading : lets you print your own error messages. You will see it in the backup script below.
Lint everything with shellcheck
shellcheck reads a script and points out quoting bugs, unused variables and traps like cd without error handling. Install it with sudo apt install shellcheck and run it before every commit, or in CI:
$ shellcheck cleanup.sh
In cleanup.sh line 3:
rm -rf $dir/*
^----^ SC2115 (warning): Use "${var:?}" to ensure this never expands to /* .
^--^ SC2086 (info): Double quote to prevent globbing and word splitting.
Each code has a wiki page explaining it. "${dir:?}" aborts when dir is empty, a second guard on top of set -u. Zero warnings is a realistic goal for every script you ship.
Build orbit-backup.sh
The team’s requirements: archive /var/lib/orbit and /etc/orbit into /var/backups/orbit/orbit-YYYYmmdd-HHMMSS.tar.gz, keep the newest 7, log to stdout and errors to stderr, and exit non-zero on any failure so the scheduler notices. If you skipped ahead, create the inputs first:
$ sudo mkdir -p /var/lib/orbit /etc/orbit
$ echo "PORT=3000" | sudo tee /etc/orbit/orbit.env > /dev/null
$ echo '{"note":"hello"}' | sudo tee /var/lib/orbit/notes.json > /dev/null
The script is built from five decisions, in the order they appear in the file:
- Strict mode, settings with defaults, and
umask 077: the archive containsorbit.env, so only root may read it. - Logging helpers, and
getoptsfor-dand-kso you can test with another directory. - Checks before any work: running as root, sources exist,
KEEPis a positive number. - Write to a
.partialfile, verify it withtar -tzf, then rename. A half-written archive never looks like a valid backup, and theEXITtrap deletes it on failure. - Prune: list archives newest first (the timestamp sorts correctly as text) and delete everything after the first
KEEP.
#!/usr/bin/env bash
# orbit-backup.sh: archive Orbit data and configuration, keep the newest N archives.
set -euo pipefail
umask 077
readonly SOURCES=(/var/lib/orbit /etc/orbit)
DEST_DIR="/var/backups/orbit"
KEEP=7
TMP_FILE=""
log() { printf '%s INFO %s\n' "$(date '+%F %T')" "$*"; }
warn() { printf '%s WARN %s\n' "$(date '+%F %T')" "$*" >&2; }
die() { printf '%s ERROR %s\n' "$(date '+%F %T')" "$*" >&2; exit 1; }
usage() {
cat <<EOF
Usage: $(basename "$0") [-d DIR] [-k COUNT]
-d DIR where to store archives (default: $DEST_DIR)
-k COUNT number of archives to keep (default: $KEEP)
EOF
}
cleanup() {
if [[ -n "$TMP_FILE" && -e "$TMP_FILE" ]]; then
rm -f -- "$TMP_FILE"
warn "Removed incomplete archive $TMP_FILE"
fi
}
trap cleanup EXIT
parse_args() {
local opt OPTIND=1
while getopts ':d:k:h' opt; do
case "$opt" in
d) DEST_DIR="$OPTARG" ;;
k) KEEP="$OPTARG" ;;
h) usage; exit 0 ;;
:) die "Option -$OPTARG needs a value" ;;
*) usage >&2; die "Unknown option -$OPTARG" ;;
esac
done
}
preflight() {
[[ $EUID -eq 0 ]] || die "Run as root (the archive includes /etc/orbit/orbit.env)"
[[ "$KEEP" =~ ^[1-9][0-9]*$ ]] || die "KEEP must be a positive integer, got '$KEEP'"
local src
for src in "${SOURCES[@]}"; do
[[ -d "$src" ]] || die "Source directory not found: $src"
done
mkdir -p "$DEST_DIR"
}
create_archive() {
local target
target="$DEST_DIR/orbit-$(date +%Y%m%d-%H%M%S).tar.gz"
TMP_FILE="$target.partial"
log "Creating $target"
tar -czf "$TMP_FILE" -C / "${SOURCES[@]#/}"
tar -tzf "$TMP_FILE" > /dev/null || die "Archive failed verification"
mv -- "$TMP_FILE" "$target"
TMP_FILE=""
log "Wrote $target ($(du -h "$target" | cut -f1))"
}
prune_old() {
local -a archives
mapfile -t archives < <(find "$DEST_DIR" -maxdepth 1 -type f -name 'orbit-*.tar.gz' | sort -r)
if (( ${#archives[@]} <= KEEP )); then
log "${#archives[@]} archive(s) present, nothing to prune"
return 0
fi
local old
for old in "${archives[@]:KEEP}"; do
rm -f -- "$old"
log "Pruned $old"
done
}
main() {
parse_args "$@"
preflight
create_archive
prune_old
log "Backup finished"
}
main "$@"
"${SOURCES[@]#/}" strips the leading / from each element, so with -C / the archive stores var/lib/orbit/... and restores cleanly anywhere. "${archives[@]:KEEP}" is an array slice: every element from index KEEP on. rm -f -- stops a file name starting with - from being read as an option. Calling main "$@" on the last line means Bash has read the whole file before anything runs. Install and try it:
$ sudo install -m 755 orbit-backup.sh /usr/local/bin/orbit-backup.sh
$ sudo orbit-backup.sh
2026-11-03 02:15:00 INFO Creating /var/backups/orbit/orbit-20261103-021500.tar.gz
2026-11-03 02:15:00 INFO Wrote /var/backups/orbit/orbit-20261103-021500.tar.gz (4.0K)
2026-11-03 02:15:00 INFO 1 archive(s) present, nothing to prune
2026-11-03 02:15:00 INFO Backup finished
$ sudo orbit-backup.sh -k 0; echo "exit=$?"
2026-11-03 02:15:09 ERROR KEEP must be a positive integer, got '0'
exit=1
Practice lab
The backup script is in place. Before lesson 15 schedules it, prove it behaves:
- Run
shellcheckon the script and fix anything it reports. - Run the script nine times (a loop with
sleep 1between runs) and confirm that exactly seven archives remain. - Make it fail: temporarily rename
/etc/orbit, run it, check the exit code and that no.partialfile is left behind. Rename it back. - Restore the newest archive into
/tmp/restoreand compareorbit.envwith the original.
Show a solution
shellcheck /usr/local/bin/orbit-backup.sh should print nothing. Run for i in $(seq 9); do sudo orbit-backup.sh; sleep 1; done, then ls /var/backups/orbit | wc -l prints 7 (the sleep keeps the one-second timestamps unique). For the failure, sudo mv /etc/orbit /etc/orbit.off, then sudo orbit-backup.sh; echo $? logs “Source directory not found” to stderr and prints 1, and ls /var/backups/orbit/*.partial finds nothing; put it back with sudo mv /etc/orbit.off /etc/orbit. To restore, newest=$(ls -1 /var/backups/orbit/orbit-*.tar.gz | tail -1), sudo mkdir -p /tmp/restore, sudo tar -xzf "$newest" -C /tmp/restore and sudo diff /etc/orbit/orbit.env /tmp/restore/etc/orbit/orbit.env, which prints nothing when the files match.
Exercise
A cleanup script runs rm -rf “$BUILD_DIR”/cache, but BUILD_DIR was misspelled as BUILD_DRI where it is set. Which setting stops the script before rm deletes /cache?
Show answer
Answer: B. With set -u, referencing an unset variable aborts the script. Without it, “$BUILD_DIR”/cache silently becomes /cache. set -x only shows what happened after the fact.
Exercise
A nightly job runs pg_dump orbit | gzip > db.sql.gz under set -e. The database was down, yet the job exited 0 and left a tiny file. What fixes the false success?
Show answer
Answer: D. A pipeline’s exit status is normally that of its last command, and gzip succeeded. pipefail makes the pipeline report the failure of any command in it, and set -e then stops the script.
Exercise
Your loop for f in $(ls /var/backups/orbit) breaks on a file named “orbit old.tar.gz”. What is the robust replacement?
Show answer
Answer: C. Globs expand to one word per file, spaces included, and quoting “$f” keeps it intact. Quoting the whole $(ls) gives one single word containing every name.
Key takeaways
- Start every script with a shebang and
set -euo pipefail, and know where-edoes not fire. - Quote every expansion:
"$var","$@","${array[@]}". - Exit codes are your script’s contract: 0 for success, non-zero with a message on stderr for failure.
- Use functions with
local,trap ... EXITfor cleanup and here-docs for usage text. - Write to a temporary file, verify, then rename, and run
shellcheckon everything you ship.
FAQ
Should I use #!/bin/bash or #!/usr/bin/env bash?
On Linux servers both work, because Bash lives at /bin/bash. #!/usr/bin/env bash finds Bash through the PATH, which matters on macOS with a newer Homebrew Bash or on BSDs. Avoid #!/bin/sh for scripts that use arrays, [[ ]] or other Bash features: on Ubuntu sh is dash, which does not support them.
Is set -euo pipefail always a good idea?
For automation scripts, yes: it turns silent failures into visible ones. Know its gaps: -e ignores failures inside if conditions and &&/|| lists, and some commands return non-zero on purpose (grep with no match, (( 0 ))). Handle those explicitly, for example grep -q pattern file || true. Do not put it in your interactive shell or in files you source into one.
What is the difference between [ ] and [[ ]]?
[ is an ordinary command (also called test), so unquoted variables inside it are split and globbed, and you need -a/-o for logic. [[ is Bash syntax: no splitting inside, && and || work, == supports glob patterns and =~ regular expressions. Use [[ ]] in Bash scripts and [ ] only in portable sh scripts.
How do I debug a Bash script?
Run it with bash -x script.sh to print every command with variables expanded, or add set -x and set +x around the part you suspect. bash -n script.sh checks syntax without running anything, and shellcheck catches most bugs before you run it at all. Logging helpers with timestamps make production failures readable later.
When should I switch from Bash to Python?
When the script needs real data structures, JSON or API handling beyond a quick jq, careful error handling across many steps, or grows past a couple of hundred lines. Bash shines at gluing commands and files together; Python is better at logic. Many teams keep a Bash wrapper that calls a Python tool.