Chapter 2: Linux & Shell

The ls command lists directory contents, but its flags unlock its real power. -l provides long format showing permissions, owner, size, and modification date. -a shows hidden files (those starting with a dot, like .env and .bashrc). -h converts sizes to human-readable format (KB, MB, GB). -t sorts by modification time (newest first). -S sorts by file size (largest first).

Combine them: ls -lahS shows everything including hidden files, with human-readable sizes, sorted by size. This is the first command to run when investigating disk usage in a directory full of model checkpoints.

The find command locates files by matching criteria. Search by name (find . -name '*.py'), by size (find . -size +100M for files over 100MB), by modification time (find . -mtime -7 for files changed in the last 7 days), or by type (find . -type d for directories only).

The -exec flag runs a command on each result: find . -name '*.pyc' -delete removes all compiled Python files. For ML projects, find is essential for locating checkpoints, cleaning up cache files, and auditing large files that might be consuming disk space.

grep searches file contents for patterns. The most useful flags: -r (recursive search through directories), -n (show line numbers), -i (case insensitive), -l (show only filenames that match, not the matching lines), and -c (count matches). Extended regex with -E enables patterns like grep -E 'error|exception|fail'.

For ML work, grep is indispensable for searching training logs (grep 'OOM' logs/*.log), finding configuration values (grep -r 'learning_rate' configs/), and locating code patterns (grep -rn 'import torch' src/).

The pipe operator (|) connects the output (stdout) of one command to the input (stdin) of the next. This enables powerful command chains: nvidia-smi | grep 'MiB' extracts memory usage lines from GPU status. cat train.log | grep 'loss' | tail -20 shows the last 20 lines containing 'loss'.

Pipes chain simple tools into powerful workflows. Each Unix tool does one thing well — ls lists files, grep filters text, sort orders lines, head/tail selects portions — and pipes combine them. This composability is the philosophical foundation of Unix and the reason the command line remains essential.

Redirection sends command output to files instead of the terminal. > writes to a file (overwriting existing content). >> appends to a file. 2>&1 redirects stderr to the same destination as stdout. 2>/dev/null discards error messages.

The essential ML pattern: python train.py > train.log 2>&1 & runs training in the background, captures all output (both normal and error) to a log file. Without 2>&1, error messages (CUDA errors, OOM messages) would go to the terminal and be lost. The trailing & runs the process in the background.

A newer generation of tools improves on the classics. fd is a simpler find with sensible defaults. ripgrep (rg) searches recursively, in parallel, and skips files listed in .gitignore, which makes it much faster than grep -r on large repositories. bat is cat with syntax highlighting and line numbers, fzf adds fuzzy, interactive selection to any list, and eza is a modern ls. ncdu browses disk usage. They are worth installing on machines you use daily. Scripts that run on servers should still use the POSIX tools, because those are always present while the new ones often are not.

Every running process has a unique Process ID (PID) assigned by the kernel. Use ps aux | grep python to find training processes and their PIDs. kill <PID> sends SIGTERM for a graceful shutdown. pgrep -f train.py finds PIDs by command name without the grep gymnastics.

PIDs are sequential and wrap around after reaching the maximum (typically 32768 or 4194304 on modern systems). The init process always has PID 1. Child processes inherit their parent's PID as their PPID (Parent PID), forming a process tree you can view with pstree.

nvidia-smi is the essential GPU monitoring tool. It shows GPU utilization percentage, memory usage (used/total), temperature, power consumption, and all processes running on each GPU. Key usage patterns: nvidia-smi -l 1 refreshes every second for real-time monitoring. nvidia-smi --query-gpu=gpu_name,utilization.gpu,memory.used --format=csv produces machine-parseable output for scripts.

The --query-compute-apps flag shows per-process GPU memory usage, helping you identify which training jobs or zombie processes are consuming GPU memory. When a training job crashes but doesn't release GPU memory, nvidia-smi reveals the leaked process so you can kill it.

nohup (no hangup) prevents a process from being killed when your SSH session disconnects. The command nohup python train.py & runs training in the background, immune to the SIGHUP signal. Output is redirected to nohup.out by default.

nohup is simple but limited — you can't reattach to see live output, you can't scroll back through output history, and managing multiple nohup processes is cumbersome. For anything beyond a quick one-off job, use tmux instead.

tmux (terminal multiplexer) creates persistent terminal sessions that survive SSH disconnections. You create a named session (tmux new -s training), start your training job, detach (Ctrl+B then D), close your SSH connection, and the training continues. Later, you reattach (tmux attach -t training) from any SSH connection and see your training exactly where you left it.

tmux also supports splitting the terminal into panes (Ctrl+B then % for vertical split, " for horizontal) and multiple windows (Ctrl+B then C for new window). A typical setup: left pane runs training, right pane shows nvidia-smi -l 2 for real-time GPU monitoring.

Appending & to a command runs it in the background, returning control of the terminal immediately. jobs lists all background jobs in the current shell. fg brings a background job to the foreground. fg %2 brings job number 2 to the foreground. Ctrl+Z suspends (pauses) the current foreground process, and bg resumes it in the background.

Background jobs are tied to your shell session — if you close the terminal, they receive SIGHUP and typically terminate (unless you used nohup or disown). For persistent background execution, always use tmux.

Linux signals control process behavior. The most important for ML work: SIGTERM (signal 15) asks a process to shut down gracefully — PyTorch signal handlers can catch this and save a checkpoint before exiting. SIGKILL (signal 9) forces immediate termination with absolutely no cleanup — the process cannot catch or ignore it. SIGSTOP pauses a process (useful for temporarily freeing CPU), and SIGCONT resumes it.

Always try SIGTERM (kill <PID>) before SIGKILL (kill -9 <PID>). SIGTERM gives the training script a chance to save progress. SIGKILL should be a last resort for completely stuck processes that don't respond to SIGTERM.

Each user on a Linux system has a unique username, a numeric user ID (UID), a home directory (typically /home/username), and a default shell. The useradd command creates users, and passwd sets passwords. User account information is stored in /etc/passwd (readable by all), while encrypted passwords are in /etc/shadow (readable only by root).

On GPU servers, each team member should have their own user account. This provides isolation (each user's processes run under their own UID), accountability (you can track who ran which training jobs), and security (users can't accidentally access each other's API keys stored in home directories).

Groups are collections of users that share file access permissions. The groupadd command creates a group, and usermod -aG ml-team alice adds alice to the ml-team group without removing her from existing groups (the -a flag is critical — without it, usermod replaces all groups).

Groups enable collaborative access to datasets and models. Set up a shared /data/ directory owned by the ml-team group with permissions 2775 (the setgid bit ensures new files inherit the group), and every team member can read and write shared training data without needing root.

The sudo command runs a single command as root (or another user). The /etc/sudoers file controls who can use sudo and which commands they can run. Never share the root password — use sudo with individual accounts for accountability and complete audit trails.

The sudoers file supports granular control: alice ALL=(ALL) /usr/bin/apt, /usr/bin/pip allows alice to install packages but nothing else. %ml-team ALL=(ALL) /usr/bin/nvidia-smi allows the entire team to check GPU status with sudo.

Every file has a user owner and a group owner. New files inherit the creating user's ownership by default. The chown user:group file command changes ownership. The setgid bit (chmod g+s dir/) changes inheritance behavior for directories — new files in that directory inherit the directory's group rather than the creating user's primary group.

This is essential for shared workspaces. Without setgid, if Alice creates a checkpoint file in /data/models/, it belongs to alice:alice and Bob can't write to it. With setgid on /data/models/, the file belongs to alice:ml-team and Bob (as an ml-team member) has full access.

Each team member should generate their own SSH key pair. The server's ~/.ssh/authorized_keys file (one per user) lists the public keys allowed to authenticate as that user. Revoking access means removing the corresponding public key from the file.

For teams: consider a centralized SSH key management approach. GitHub or GitLab can serve as a key authority (ssh-import-id gh:username imports keys from GitHub). For larger teams, an LDAP or FreeIPA server centralizes both user accounts and SSH keys, making onboarding and offboarding much simpler.

umask sets which permission bits are removed from newly created files and directories. Programs usually request 666 for files and 777 for directories, and the kernel clears every bit that is set in the umask. With umask 022, files become 644 and directories 755: readable by everyone, writable only by the owner. With 002, they become 664 and 775, so the group can write too, which suits shared project directories. It is a mask, not subtraction: umask 033 turns 666 into 644, not 633. Set it in your shell profile or in a systemd service's UMask setting.

The first line of a shell script, #!/bin/bash, tells the operating system which interpreter to use for executing the file. This is called the shebang (or hashbang). Without it, the system tries to run the script with the current shell, which may have different behavior.

The more portable alternative #!/usr/bin/env bash searches the system PATH for bash rather than assuming a fixed location. This works on systems where bash might be installed at /usr/local/bin/bash instead of /bin/bash (common on macOS).

Assign with name=value and no spaces around the equals sign, since spaces turn it into a command with arguments. Read a variable by writing a dollar sign before its name, or before the name in braces when text follows it. Always put expansions in double quotes. Unquoted, the value is split on whitespace and expanded as a glob, so a path with a space becomes two arguments. Command substitution, a dollar sign followed by a command in parentheses, captures that command's output, which is handy for timestamped experiment directories. The braces form also supplies defaults, so a script argument can fall back to a value when it is missing.

Bash conditionals use if [ condition ]; then ... fi syntax. Test flags include: -f (file exists), -d (directory exists), -z (string is empty), -n (string is non-empty), -eq/-ne/-lt/-gt (numeric comparisons). Double brackets [[ ]] support regex matching and are generally preferred for their safer behavior (no word splitting inside).

For ML scripts, conditionals check prerequisites: does the CUDA device exist? Is the dataset directory populated? Is there enough disk space? These pre-flight checks prevent training jobs from failing hours into a run due to a missing file or full disk.

A for loop runs its body once per word: for gpu in 0 1 2 3, or for cfg in configs/*.yaml for every matching file. A while loop runs while a command succeeds; while IFS= read -r line, with a file redirected in, processes a file line by line without mangling backslashes or spaces. To launch runs in parallel, end the command inside the loop body with an ampersand, as in python train.py with a learning-rate argument followed by an ampersand, and then call wait after the loop so the script blocks until every run has finished. Writing an ampersand followed by a semicolon is a syntax error.

A function names a block of commands: define it as name() followed by the body in braces, then call it like any command with arguments, which it reads as positional parameters. It returns an exit status with return, 0 for success, so if check_gpu_free; then works naturally. To return data, print it and capture it with command substitution. Variables are global by default, so declare helpers' variables with local to avoid overwriting a caller's loop variable. Functions such as check_disk, make_run_dir and cleanup keep a growing launcher script readable and let you test steps one at a time.

Three critical settings for robust scripts: set -e exits immediately on the first command that fails (non-zero exit code). set -u treats references to unset variables as errors (catches typos). set -o pipefail makes pipes fail if any command in the chain fails (by default, only the last command's exit code matters).

Combine them as set -euo pipefail at the top of every script. The trap command registers cleanup functions that run when the script exits (success or failure), ensuring temporary files are removed and background processes are killed. For ML scripts, trap can save a partial checkpoint or send a notification on failure.

apt manages operating system packages: nginx, git, build-essential, libcudnn8. pip manages Python packages: torch, numpy, scikit-learn. These are separate ecosystems that should not be mixed carelessly.

Never run sudo pip install — this installs Python packages into the system Python, potentially breaking system tools (many Ubuntu system utilities are written in Python). Always install ML packages in a virtual environment or conda environment. The system Python should only be modified through apt.

Python's built-in venv module creates isolated Python environments. python -m venv myenv creates a new environment, and source myenv/bin/activate activates it. Once activated, all pip installs go into the venv directory, completely separate from the system Python. deactivate returns you to the system Python.

Venvs are lightweight (only symlink to the system Python and install packages separately) but limited — they can't install non-Python dependencies or manage different Python versions. For simple projects that only need pip packages, venvs are sufficient.

conda is a cross-platform package and environment manager that installs both Python packages and native libraries, such as MKL, compilers or CUDA runtime libraries, from channels like conda-forge, without root. conda create -n proj python=3.11 makes an isolated environment with its own interpreter. That makes it useful when native dependencies are hard to get through pip. Two cautions for ML: PyTorch stopped publishing to its own conda channel in late 2024, so install PyTorch with pip inside the conda environment or from conda-forge. And mixing conda and pip installs can conflict, so install conda packages first and pip packages last.

Capturing your exact package versions ensures reproducibility. pip freeze > requirements.txt records every installed package and its version. pip install -r requirements.txt recreates the exact environment. For conda, conda env export > environment.yml captures both conda and pip packages.

For production, use pip-compile from the pip-tools package — it creates deterministic builds by resolving and pinning transitive dependencies. A simple requirements.in file listing only your direct dependencies (torch, opencv-python) gets compiled into a fully-pinned requirements.txt with every sub-dependency locked.

pyenv installs and manages multiple Python versions on a single machine. pyenv install 3.11.5 compiles Python 3.11.5 from source. pyenv local 3.11.5 sets the Python version for the current directory. This is essential when different projects require different Python versions — one project might need Python 3.10 for TensorFlow compatibility while another uses Python 3.12 for newer features.

pyenv works by inserting shims into your PATH that intercept python and pip commands, routing them to the correct Python version. It pairs well with pyenv-virtualenv for managing per-project virtual environments tied to specific Python versions.

Micromamba is a C++ reimplementation of conda that's 10-100x faster at resolving and installing packages. It's a drop-in replacement: micromamba create -n myenv pytorch works just like conda. The speed improvement comes from a compiled solver (libmamba) versus conda's older Python-based solver.

Micromamba is ideal for Docker images (where install speed directly impacts build time), CI/CD pipelines, and anyone tired of waiting minutes for conda install to solve the environment. Recent conda versions (23.10+) also use the libmamba solver by default, narrowing the speed gap.

A cron expression has five time fields: minute (0-59), hour (0-23), day-of-month (1-31), month (1-12), and day-of-week (0-7, where both 0 and 7 are Sunday). Special characters expand the syntax: * means any value, */5 means every 5th unit, 1,15 means the 1st and 15th, and 1-5 means a range from 1 to 5.

Common schedules: 0 2 * * * (daily at 2 AM), 0 */6 * * * (every 6 hours), 0 0 * * 0 (weekly on Sunday midnight), */15 * * * * (every 15 minutes). Use crontab.guru to verify expressions before deploying them.

Each user has their own crontab, edited with crontab -e and listed with crontab -l. Important caveat: cron runs commands with a minimal environment — it doesn't load your .bashrc or .profile. This means conda environments aren't activated, custom PATH entries are missing, and environment variables aren't set.

To work around this, either use absolute paths for everything, source your profile at the start of cron scripts, or set environment variables directly in the crontab (e.g., CUDA_VISIBLE_DEVICES=0 before the job line).

Systemd service files are INI-format configuration files placed in /etc/systemd/system/. They have three sections: [Unit] defines the service description and startup dependencies, [Service] specifies the command to run, the user, restart behavior, and environment variables, and [Install] determines when the service should start (usually multi-user.target for normal boot).

After creating or modifying a service file, run systemctl daemon-reload to make systemd aware of the changes. systemctl enable <service> sets it to start on boot, and systemctl start <service> starts it immediately.

Systemd's restart policies determine what happens when a service exits. Restart=always restarts on any exit (even code 0). Restart=on-failure restarts only on non-zero exit codes (appropriate for inference servers — don't restart on manual stop). RestartSec=5 waits 5 seconds between restart attempts. StartLimitBurst=5 with StartLimitIntervalSec=60 prevents rapid restart loops — if the service crashes 5 times in 60 seconds, systemd gives up.

For ML inference servers, use Restart=on-failure with RestartSec=10 to give the system time to release GPU memory between restarts.

journalctl reads the systemd journal, where all service output (both stdout and stderr) is logged. The -u flag filters by service name. -f follows in real-time (like tail -f). --since 'today' or --since '1 hour ago' limits the time range. --no-pager outputs directly to the terminal for piping.

All stdout and stderr from services configured with StandardOutput=journal go here automatically. This centralizes log management — you don't need to manage separate log files for each service.

Systemd timer units are the modern alternative to cron. They're more verbose to configure but offer features cron lacks: random delays (to prevent thundering herd effects when multiple servers run the same job), dependency on other services (only run retraining after the data pipeline service completes), persistent scheduling (run missed jobs if the server was down), and monotonic timers (run 30 minutes after boot).

For simple periodic tasks, cron is fine. For tasks that need reliability guarantees (must run even if a scheduled time was missed) or complex dependencies, systemd timers are better.

The export command makes a shell variable available to child processes. Without export, variables are only visible in the current shell — they won't be inherited by Python scripts, training processes, or other programs you launch. export API_KEY=sk-xxx makes the key available to any process started from that shell.

In scripts that launch Python training, always export variables that the Python code needs: export CUDA_VISIBLE_DEVICES=0,1 before python train.py. Otherwise, PyTorch won't see the GPU restriction.

A .env file stores key=value pairs in a plain text file, one per line. Python's python-dotenv library loads these with load_dotenv(), making them available through os.environ. This keeps configuration separate from code and makes it easy to switch between development and production settings.

Critical rule: always add .env to .gitignore. Create a .env.example file (with empty values) that documents which variables are needed. This lets new team members know what to configure without exposing actual secrets.

CUDA behavior is controlled through several environment variables. CUDA_VISIBLE_DEVICES selects which GPUs a process can see (e.g., '0,1' for the first two GPUs). CUDA_LAUNCH_BLOCKING=1 makes CUDA operations synchronous, essential for debugging — without it, CUDA errors appear at a later operation than where they actually occurred.

TORCH_CUDA_ARCH_LIST sets which GPU architectures to target when compiling CUDA kernels (e.g., '7.0;8.0;8.6' for V100, A100, and RTX 3090). Setting this correctly avoids compiling for unnecessary architectures, significantly reducing compilation time.

direnv automatically loads and unloads environment variables when you enter and leave a project directory. Create a .envrc file with dotenv (to load .env files) or export VAR=value directives. When you cd into the directory, variables are set; when you cd out, they're removed.

This is incredibly convenient for ML engineers working on multiple projects with different API keys, CUDA configurations, and virtual environments. Each project directory has its own .envrc that sets everything up automatically — no manual activation or sourcing required.

For development, .env files are adequate. For production, use dedicated secrets managers: AWS Secrets Manager, GCP Secret Manager, or HashiCorp Vault. These provide access control (who can read which secrets), audit trails (who accessed what and when), automatic rotation (change API keys without redeploying), and encryption at rest.

Note that environment variables are not truly secret on a Linux machine — they're visible in /proc/PID/environ to anyone with access to the process. In high-security environments, inject secrets through mounted files or in-memory vaults rather than environment variables.

envsubst, from GNU gettext, copies standard input to standard output and replaces references to environment variables, written in shell style with a dollar sign, with their values. envsubst with config.template.yml redirected in and config.yml redirected out produces a filled-in config at deploy time. Commit the template, not the result, so real values stay out of Git. Two cautions. Unset variables become empty strings without any error, so check required variables first. And it replaces every reference it sees, so pass a list of the allowed variable names as its argument to leave other text untouched.