Add ripcord/README.md

ripcord/README.md

@@ -0,0 +1,115 @@
+# Ripcord
+
+A dead-simple parachute for your server's disk.
+
+### The Problem
+
+A full disk can crash a server and corrupt data. When this happens, you are locked out and cannot fix the problem.
+
+### The Solution
+
+Ripcord runs once on a new system's first boot. It creates a single, large "ballast" file of **uncompressible random data**.
+
+In an emergency, you delete this one file. This instantly frees up critical disk space, giving you time to log in and properly resolve the issue.
+
+---
+
+## In an Emergency: Pull The Ripcord
+
+To prevent a disk-full event and recover your system, **delete this file**:
+
+```bash
+# This is it. This is the command that saves the server.
+rm /RIPCORD_EMERGENCY_DELETE_FOR_DISK_SPACE.dat
+```
+
+This single action gives you the breathing room you need.
+
+---
+
+### Installation
+
+Installation is a two-step process: place the script, then enable the service for your OS.
+
+#### 1. Place the Script (All Systems)
+
+Copy `ripcord.sh` to `/usr/local/sbin/` and make it executable.
+
+```bash
+sudo cp ripcord.sh /usr/local/sbin/ripcord.sh
+sudo chmod +x /usr/local/sbin/ripcord.sh
+```
+
+#### 2. Enable the First-Boot Service
+
+Choose the instructions for your operating system.
+
+##### A) For Debian / Ubuntu / RHEL (systemd)
+
+```bash
+# Create and enable the systemd service. It will run once on the next boot.
+cat << EOF | sudo tee /etc/systemd/system/ripcord.service
+[Unit]
+Description=Ripcord Emergency Disk Space Reserve
+[Service]
+Type=oneshot
+ExecStart=/usr/local/sbin/ripcord.sh
+ExecStartPost=/bin/sh -c "systemctl disable ripcord.service"
+[Install]
+WantedBy=multi-user.target
+EOF
+
+sudo systemctl enable ripcord.service
+```
+
+##### B) For FreeBSD (rc.d)
+
+```bash
+# Create the rc.d script.
+cat << EOF | sudo tee /usr/local/etc/rc.d/ripcord
+#!/bin/sh
+# PROVIDE: ripcord
+# REQUIRE: LOGIN
+. /etc/rc.subr
+name="ripcord"
+start_cmd="${name}_start"
+stop_cmd=":"
+ripcord_start() {
+    if [ ! -f "/var/log/ripcord-deployed.flag" ]; then
+        /usr/local/sbin/ripcord.sh
+    fi
+}
+load_rc_config \$name
+run_rc_command "\$1"
+EOF
+
+# Make it executable and enable it in rc.conf.
+sudo chmod +x /usr/local/etc/rc.d/ripcord
+sudo sysrc ripcord_enable="YES"
+```
+
+##### C) For OpenBSD (rc.local)
+
+```bash
+# Add the execution command to /etc/rc.local.
+# This block will be checked on every boot, but only run once.
+cat << EOF | sudo tee -a /etc/rc.local
+
+# Deploy Ripcord on first boot if not already done
+if [ ! -f "/var/log/ripcord-deployed.flag" ] && [ -x "/usr/local/sbin/ripcord.sh" ]; then
+    /usr/local/sbin/ripcord.sh
+fi
+EOF
+```
+
+### Configuration
+
+To change the size percentage or filename, edit the variables at the top of the `ripcord.sh` script.
+
+```sh
+# Percentage of the total root filesystem size to use.
+PERCENTAGE=5
+
+# The emergency file. The name itself is the instruction.
+TARGET_FILE="/RIPCORD_EMERGENCY_DELETE_FOR_DISK_SPACE.dat"
+```