From 76e480e756219b357f510c893f9209e8bfa85824 Mon Sep 17 00:00:00 2001
From: tschettervictor <tschetter.victor@gmail.com>
Date: Mon, 5 May 2025 17:44:59 -0600
Subject: [PATCH] docs: Add migrate docs

---
 docs/chapters/migration.rst           | 39 ++++++++++++++++++++++++++-
 docs/chapters/subcommands/migrate.rst | 18 +++++++++++++
 usr/local/share/bastille/migrate.sh   | 26 +++++++++++-------
 3 files changed, 72 insertions(+), 11 deletions(-)
 create mode 100644 docs/chapters/subcommands/migrate.rst

diff --git a/docs/chapters/migration.rst b/docs/chapters/migration.rst
index 8fd05f4f..ac1d6ae4 100644
--- a/docs/chapters/migration.rst
+++ b/docs/chapters/migration.rst
@@ -1,7 +1,44 @@
-=========
 Migration
 =========
 
+Bastille
+--------
+
+Bastille supports migrations to a remote system using the ``migrate`` subcommand.
+
+Prerequisites
+^^^^^^^^^^^^^
+
+There are a couple of things that need to be in place before running the ``migrate`` command.
+
+First, you must have bastille configured both locally and remotely to use the same filesystem
+configuration. ZFS on both, or UFS on both.
+
+Second, we need a user on the remote system that has key-based authentication set up. Bastille
+does not support password-based authentication. This also implies that SSH is working on the
+remote system. This user also needs ``sudo`` permissions on the remote system.
+
+Third, if updating from a previous version, please make sure to ``diff`` your ``bastille.conf``
+file, as the ``migrate`` sub-command adds a new variable called ``bastille_migratedir``.
+
+Migration
+^^^^^^^^^
+
+To migrate a jail (or multiple jails) we can simply run
+``bastille migrate TARGET USER HOST``. This will export the jail(s), send them to the
+remote system, and import them.
+
+The ``migrate`` sub-command includes the ``-a|--auto`` option, which will auto-stop the old jail,
+migrate it, and attempt to start the migrated jail on the remote system after importing it. See the
+warning below about auto-starting the migrated jail.
+
+WARNING: Every system is unique, has different interfaces, bridges, and network configurations.
+It is possible, with the right configuration, for jails to start and work normally. But for some
+systems, it will be necessary to edit the ``jail.conf`` file of the migrated jail to get it working
+properly.
+
+You can optionally set ``-d|--destroy`` to have Bastille destroy the old jail on completion.
+
 iocage
 ------
 
diff --git a/docs/chapters/subcommands/migrate.rst b/docs/chapters/subcommands/migrate.rst
new file mode 100644
index 00000000..e3b12d2c
--- /dev/null
+++ b/docs/chapters/subcommands/migrate.rst
@@ -0,0 +1,18 @@
+migrate
+=======
+
+The ``migrate`` sub-command allows migrating the  targeted jail(s) to
+another remote system. See the chapter on Migration.
+
+This sub-command supports multiple targets.
+
+.. code-block:: shell
+
+  ishmael ~ # bastille migrate help
+  Usage: bastille migrate [option(s)] TARGET USER HOST
+
+    Options:
+
+    -a | --auto             Auto mode. Start/stop jail(s) if required.
+    -d | --destroy          Destroy local jail after migration.
+    -x | --debug            Enable debug mode.
diff --git a/usr/local/share/bastille/migrate.sh b/usr/local/share/bastille/migrate.sh
index 12a355aa..19565471 100644
--- a/usr/local/share/bastille/migrate.sh
+++ b/usr/local/share/bastille/migrate.sh
@@ -33,7 +33,7 @@
 . /usr/local/share/bastille/common.sh
 
 usage() {
-    error_notify "Usage: bastille migrate [option(s)] TARGET HOST [USER]"
+    error_notify "Usage: bastille migrate [option(s)] TARGET USER HOST"
     cat << EOF
 	
     Options:
@@ -88,16 +88,16 @@ if [ "$#" -ne 3 ]; then
 fi
 
 TARGET="${1}"
-HOST="${2}"
-USER="${3}"
+USER="${2}"
+HOST="${3}"
 
 bastille_root_check
 set_target "${TARGET}"
 
 validate_host_status() {
 
-    local _host="${1}"
-    local _user="${2}"
+    local _user="${1}"
+    local _host="${2}"
     
     info "\nChecking remote host status..."
 
@@ -158,8 +158,8 @@ migrate_create_export() {
 migrate_jail() {
 
     local _jail="${1}"
-    local _host="${2}"
-    local _user="${3}"
+    local _user="${2}"
+    local _host="${3}"
 
     local _remote_bastille_zfs_enable="$(ssh ${_user}@${_host} sysrc -f /usr/local/etc/bastille/bastille.conf -n bastille_zfs_enable)"
     local _remote_bastille_jailsdir="$(ssh ${_user}@${_host} sysrc -f /usr/local/etc/bastille/bastille.conf -n bastille_jailsdir)"
@@ -229,16 +229,22 @@ migrate_jail() {
         error_exit "[ERROR]: Failed to import jail on remote system."
     fi
 
-    # Destroy old jail if FORCE=1
+    # Destroy old jail if OPT_DESTROY=1
     if [ "${OPT_DESTROY}" -eq 1 ]; then
         bastille destroy -af "${_jail}"
     fi
 
+    # Remove archives
     migrate_cleanup "${_jail}"
+
+    # Start new jail if AUTO=1
+    if [ "${AUTO}" -eq 1 ]; then
+        ssh ${_user}@${_host} sudo bastille start "${_jail}"
+    fi
 }
 
 # Validate host uptime
-validate_host_status "${HOST}" "${USER}"
+validate_host_status "${USER}" "${HOST}"
 
 for _jail in ${JAILS}; do
 
@@ -257,7 +263,7 @@ for _jail in ${JAILS}; do
 
     migrate_create_export "${_jail}"
     
-    migrate_jail "${_jail}" "${HOST}" "${USER}"
+    migrate_jail "${_jail}" "${USER}" "${HOST}"
 
     info "\nSuccessfully migrated '${_jail}' to '${HOST}'.\n"