.. _lifepreserver:

lifepreserver
*************

The lifepreserver class is used to manage and retrieve information about
scheduled snapshots and replication.

Every lifepreserver class request contains the following parameters:

+---------------+---------------+---------------------------------------+
| **Parameter** | **Value**     | **Description**                       |
|               |               |                                       |
+===============+===============+=======================================+
| id            |               | Any unique value for the request,     |
|               |               | including a hash, checksum, or uuid.  |
+---------------+---------------+---------------------------------------+
| name          | lifepreserver |                                       |
|               |               |                                       |
+---------------+---------------+---------------------------------------+
| namespace     | sysadm        |                                       |
|               |               |                                       |
+---------------+---------------+---------------------------------------+
| action        |               | Actions include "addreplication",     |
|               |               | "createsnap", "cronscrub", "cronsnap" |
|               |               | "initreplication", "listcron",        |
|               |               | "listreplication", "listsnap",        |
|               |               | "removesnap", "removereplication",    |
|               |               | "revertsnap", "runreplication",       |
|               |               | "savesettings", and "settings"        |
+---------------+---------------+---------------------------------------+

The rest of this section provides examples of the available *actions*
for each type of request, along with their responses.

.. index:: listcron, Life Preserver

.. _List Schedules:

List Schedules
==============

The "listcron" action retrieves the information for each Life Preserver
scheduled task. If snapshots have been configured for a ZFS pool, it
lists the number of snapshots to keep and the time that snapshots are
taken. If scrubs have been configured on that ZFS pool, it also lists
the time that ZFS scrubs occur.

**REST Request**

::

 PUT /sysadm/lifepreserver
 {
   "action" : "listcron"
 }

**REST Response**

.. code-block:: json

 {
    "args": {
        "listcron": {
            "tank1": {
                "keep": "3",
                "schedule": "daily@18"
                "scrub": "daily@22"
            }
        }
    }
 }

**WebSocket Request**

.. code-block:: json

 {
   "args" : {
      "action" : "listcron"
   },
   "name" : "lifepreserver",
   "namespace" : "sysadm",
   "id" : "fooid"
 }

**WebSocket Response**

.. code-block:: json

 {
  "args": {
    "listcron": {
      "tank1": {
        "keep": "3",
        "schedule": "daily@18"
        "scrub": "daily@22"
      }
    }
  },
  "id": "fooid",
  "name": "response",
  "namespace": "sysadm"
 }

.. index:: cronsnap, Life Preserver

.. _Create a Snapshot Schedule:

Create a Snapshot Schedule
==========================

The "cronsnap" action is used to create snapshot schedules for Life
Preserver. This action supports the following parameters:

+---------------+------------------------------------------------------+
| **Parameter** | **Description**                                      |
|               |                                                      |
+===============+======================================================+
| pool          | Name of the ZFS pool to snapshot.                    |
|               |                                                      |
+---------------+------------------------------------------------------+
| keep          | Specify the number of snapshots to keep.             |
|               |                                                      |
+---------------+------------------------------------------------------+
| frequency     | Specify when to take the snapshots. Possible values  |
|               | are "daily@XX" (where XX is the number of the hour), |
|               | "hourly", "30min", "10min", "5min" or "none"         |
|               | (disables snapshots)                                 |
+---------------+------------------------------------------------------+

**REST Request**

::

  PUT /sysadm/lifepreserver
  {
    "pool" : "mytank",
    "keep" : "10",
    "frequency" : "daily@11",
    "action" : "cronsnap"
  }

**REST Response**

.. code-block:: json

 {
    "args": {
        "cronsnap": {
            "frequency": "daily@11",
            "keep": "10",
            "pool": "mytank"
        }
    }
 }

**WebSocket Request**

.. code-block:: json

 {
   "args" : {
      "action" : "cronsnap",
      "keep" : "10",
      "frequency" : "daily@11",
      "pool" : "mytank"
   },
   "namespace" : "sysadm",
   "name" : "lifepreserver",
   "id" : "fooid"
 }

**WebSocket Response**

.. code-block:: json

 {
  "args": {
    "cronsnap": {
      "frequency": "daily@11",
      "keep": "10",
      "pool": "mytank"
    }
  },
  "id": "fooid",
  "name": "response",
  "namespace": "sysadm"
 }

.. index:: cronscrub, Life Preserver

.. _Create a Scrub Schedule:

Create a Scrub Schedule
=======================

The "cronscrub" action is used to schedule a ZFS scrub. This action
supports the following parameters:

+---------------+----------------------------------------------------+
| **Parameter** | **Description**                                    |
|               |                                                    |
+===============+====================================================+
| pool          | Name of ZFS pool to scrub.                         |
|               |                                                    |
+---------------+----------------------------------------------------+
| frequency     | Specify when to perform the scrub. Possible values |
|               | are "daily@XX", "weekly@YY@XX", and monthly@ZZ@XX, |
|               | where "XX" is the hour, "YY" is the day of week    |
|               | ("01" for Monday through "07" for Sunday), "ZZ" is |
|               | the day of month, and "none"disables scrubs.       |
|               |                                                    |
+---------------+----------------------------------------------------+

**REST Request**

::

 PUT /sysadm/lifepreserver
 {
   "action" : "cronscrub",
   "pool" : "tank",
   "frequency" : "daily@22"
 }

**REST Response**

.. code-block:: json

 {
    "args": {
        "cronscrub": {
            "frequency": "daily@22",
            "pool": "tank"
        }
    }
 }

**WebSocket Request**

.. code-block:: json

 {
   "args" : {
      "action" : "cronscrub",
      "pool" : "tank",
      "frequency" : "daily@22"
   },
   "namespace" : "sysadm",
   "name" : "lifepreserver",
   "id" : "fooid"
 }

**WebSocket Response**

.. code-block:: json

 {
  "args": {
    "cronscrub": {
      "frequency": "daily@22",
      "pool": "tank"
    }
  },
  "id": "fooid",
  "name": "response",
  "namespace": "sysadm"
 }

.. index:: createsnap, Life Preserver

.. _Create a Snapshot:

Create a Snapshot
=================

The "createsnap" action creates a one-time snapshot of the specified
dataset.

**REST Request**

::

 PUT /sysadm/lifepreserver
 {
   "snap" : "mytestsnap",
   "dataset" : "tank",
   "comment" : "Testing",
   "action" : "createsnap"
 }

**WebSocket Request**

.. code-block:: json

 {
   "args" : {
      "comment" : "Testing",
      "dataset" : "tank",
      "action" : "createsnap",
      "snap" : "mytestsnap"
   },
   "name" : "lifepreserver",
   "namespace" : "sysadm",
   "id" : "fooid"
 }

**Response**

.. code-block:: json

 {
  "args": {
    "createsnap": {
      "comment": "Testing",
      "dataset": "tank",
      "snap": "mytestsnap"
    }
  },
  "id": "fooid",
  "name": "response",
  "namespace": "sysadm"
 }

.. index:: listsnap, Life Preserver

.. _List Snapshots:

List Snapshots
==============

The "listsnap" action retrieves the list of saved snapshots.

**REST Request**

::

 PUT /sysadm/lifepreserver
 {
   "pool" : "tank1",
   "action" : "listsnap"
 }

**REST Response**

.. code-block:: json

 {
    "args": {
        "listsnap": {
            "tank1@auto-2016-01-04-18-00-00": {
                "comment": "Automated Snapshot"
            },
            "tank1@auto-2016-01-05-18-00-00": {
                "comment": "Automated Snapshot"
            },
            "tank1@auto-2016-01-06-18-00-00": {
                "comment": "Automated Snapshot"
            },
            "tank1@auto-2016-01-07-18-00-00": {
                "comment": "Automated Snapshot"
            }
        }
    }
 }

**WebSocket Request**

.. code-block:: json

 {
   "name" : "lifepreserver",
   "args" : {
      "pool" : "tank1",
      "action" : "listsnap"
   },
   "namespace" : "sysadm",
   "id" : "fooid"
 }

**WebSocket Response**

.. code-block:: json

 {
  "args": {
    "listsnap": {
      "tank1@auto-2016-01-04-18-00-00": {
        "comment": "Automated Snapshot"
      },
      "tank1@auto-2016-01-05-18-00-00": {
        "comment": "Automated Snapshot"
      },
      "tank1@auto-2016-01-06-18-00-00": {
        "comment": "Automated Snapshot"
      },
      "tank1@auto-2016-01-07-18-00-00": {
        "comment": "Automated Snapshot"
      }
    }
  },
  "id": "fooid",
  "name": "response",
  "namespace": "sysadm"
 }

.. index:: revertsnap, Life Preserver

.. _Revert a Snapshot:

Revert a Snapshot
=================

The "revertsnap" action is used to rollback the contents of the
specified dataset to the point in time that the specified snapshot was
taken.

.. danger:: Performing this operation will revert the contents of the
            dataset back in time, meaning that all changes to the
            dataset's files that occurred since the snapshot was taken
            will be lost.

**REST Request**

::

 PUT /sysadm/lifepreserver
 {
   "snap" : "auto-2016-01-09-18-00-00",
   "dataset" : "tank1/usr/jails",
   "action" : "revertsnap"
 }

**REST Response**

.. code-block:: json

 {
    "args": {
        "revertsnap": {
            "dataset": "tank1/usr/jails",
            "snap": "auto-2016-01-09-18-00-00"
        }
    }
 }

**WebSocket Request**

.. code-block:: json

 {
   "args" : {
      "dataset" : "tank1/usr/jails",
      "action" : "revertsnap",
      "snap" : "auto-2016-01-09-18-00-00"
   },
   "namespace" : "sysadm",
   "name" : "lifepreserver",
   "id" : "fooid"
 }

**WebSocket Response**

.. code-block:: json

 {
  "args": {
    "revertsnap": {
      "dataset": "tank1/usr/jails",
      "snap": "auto-2016-01-09-18-00-00"
    }
  },
  "id": "fooid",
  "name": "response",
  "namespace": "sysadm"
 }

.. index:: removesnap, Life Preserver

.. _Remove a Snapshot:

Remove a Snapshot
=================

The "removesnap" action is used to remove a ZFS snapshot from the
specified dataset or pool.

**REST Request**

::

 PUT /sysadm/lifepreserver
 {
   "dataset" : "tank1/usr/jails",
   "snap" : "auto-2016-01-09-18-00-00",
   "action" : "removesnap"
 }

**REST Response**

.. code-block:: json

 {
    "args": {
        "removesnap": {
            "dataset": "tank1/usr/jails",
            "snap": "auto-2016-01-09-18-00-00"
        }
    }
 }

**WebSocket Request**

.. code-block:: json

 {
   "args" : {
      "snap" : "auto-2016-01-09-18-00-00",
      "action" : "removesnap",
      "dataset" : "tank1/usr/jails"
   },
   "name" : "lifepreserver",
   "namespace" : "sysadm",
   "id" : "fooid"
 }

**WebSocket Response**

.. code-block:: json

 {
  "args": {
     "removesnap": {
        "dataset": "tank1/usr/jails",
        "snap": "auto-2016-01-09-18-00-00"
     }
  },
  "id": "fooid",
  "name": "response",
  "namespace": "sysadm"
 }

.. index:: addreplication, Life Preserver

.. _Add Replication:

Add Replication
===============

The "addreplication" action is used to create a replication task in Life
Preserver. This action supports several parameters:

+---------------+-----------------------------------------------------+
| **Parameter** | **Description**                                     |
|               |                                                     |
+===============+=====================================================+
| host          | Remote hostname or IP address.                      |
|               |                                                     |
+---------------+-----------------------------------------------------+
| port          | SSH port number on remote system.                   |
|               |                                                     |
+---------------+-----------------------------------------------------+
| user          | User must exist on remote system.                   |
|               |                                                     |
+---------------+-----------------------------------------------------+
| password      | The password for *user* on remote system.           |
|               |                                                     |
+---------------+-----------------------------------------------------+
| dataset       | Name of local dataset to replicate.                 |
|               |                                                     |
+---------------+-----------------------------------------------------+
| remotedataset | Path to the dataset on the remote system.           |
|               |                                                     |
+---------------+-----------------------------------------------------+
| frequency     | When to replicate. Supported times are "XX" (hour), |
|               | "sync" (as snapshot is created, not recommended for |
|               | frequent snapshots), "hour" (hourly), "30min"       |
|               | (every 30 minutes), "10min" (every 10 minutes), or  |
|               | "manual" (only when requested by user)              |
|               |                                                     |
+---------------+-----------------------------------------------------+

**REST Request**

::

 PUT /sysadm/lifepreserver
 {
   "action" : "addreplication",
   "password" : "mypass",
   "dataset" : "tank1",
   "remotedataset" : "tank/backups",
   "user" : "backupuser",
   "frequency" : "22",
   "port" : "22",
   "host" : "192.168.0.10"
 }

**REST Response**

.. code-block:: json

 {
    "args": {
        "addreplication": {
            "frequency": "22",
            "host": "192.168.0.10",
            "ldataset": "tank1",
            "port": "22",
            "rdataset": "tank/backups",
            "user": "backupuser"
        }
    }
 }

**WebSocket Request**

.. code-block:: json

 {
   "namespace" : "sysadm",
   "name" : "lifepreserver",
   "args" : {
      "action" : "addreplication",
      "user" : "backupuser",
      "dataset" : "tank1",
      "frequency" : "22",
      "port" : "22",
      "password" : "mypass",
      "host" : "192.168.0.10",
      "remotedataset" : "tank/backups"
   },
   "id" : "fooid"
 }

**WebSocket Response**

.. code-block:: json

 {
  "args": {
    "addreplication": {
      "frequency": "22",
      "host": "192.168.0.10",
      "ldataset": "tank1",
      "port": "22",
      "rdataset": "tank/backups",
      "user": "backupuser"
    }
  },
  "id": "fooid",
  "name": "response",
  "namespace": "sysadm"
 }

.. index:: removereplication, Life Preserver

.. _Remove Replication:

Remove Replication
==================

The "removereplication" action is used to delete an existing replication
task. Note that this action only deletes the task - it does not remove
any already replicated data from the remote system.

This action supports several parameters:

+---------------+-----------------------------------------------------+
| **Parameter** | **Description**                                     |
|               |                                                     |
+===============+=====================================================+
| host          | Remote hostname or IP address.                      |
|               |                                                     |
+---------------+-----------------------------------------------------+
| dataset       | Name of local dataset to remove from replication.   |
|               |                                                     |
+---------------+-----------------------------------------------------+

**REST Request**

::

 PUT /sysadm/lifepreserver
 {
   "dataset" : "tank",
   "host" : "192.168.0.10",
   "action" : "removereplication"
 }

**REST Response**

.. code-block:: json

 {
    "args": {
        "removereplication": {
            "dataset": "tank",
            "host": "192.168.0.10"
        }
    }
 }

**WebSocket Request**

.. code-block:: json

 {
   "id" : "fooid",
   "args" : {
      "action" : "removereplication",
      "dataset" : "tank",
      "host" : "192.168.0.10"
   },
   "name" : "lifepreserver",
   "namespace" : "sysadm"
 }

**WebSocket Response**

.. code-block:: json

 {
  "args": {
    "removereplication": {
      "dataset": "tank",
      "host": "192.168.0.10"
    }
  },
  "id": "fooid",
  "name": "response",
  "namespace": "sysadm"
 }
 
.. index:: listreplication, Life Preserver

.. _List Replications:

List Replications
=================

The "listreplication" action is used to retrieve the settings of
configured replication tasks. For each task, the response includes the
name of the local ZFS pool or dataset to replicate, the IP address and
listening port number of the remote system to replicate to, when the
replication occurs (see the "frequency" description in
:ref:`Add Replication`), the name of the dataset on the remote system to
store the replicated data ("rdset"), and the name of the replication
user account.

**REST Request**

::

 PUT /sysadm/lifepreserver
 {
   "action" : "listreplication"
 }

**REST Response**

.. code-block:: json

 {
    "args": {
        "listreplication": {
            "tank1->192.168.0.9": {
                "dataset": "tank1",
                "frequency": "22",
                "host": "192.168.0.9",
                "port": "22",
                "rdset": "tank/backups",
                "user": "backups"
            }
        }
    }
 }

**WebSocket Request**

.. code-block:: json

 {
   "namespace" : "sysadm",
   "args" : {
      "action" : "listreplication"
   },
   "id" : "fooid",
   "name" : "lifepreserver"
 }

**WebSocket Response**

.. code-block:: json

 {
  "args": {
    "listreplication": {
      "tank1->192.168.0.9": {
        "dataset": "tank1",
        "frequency": "22",
        "host": "192.168.0.9",
        "port": "22",
        "rdset": "tank/backups",
        "user": "backups"
      }
    }
  },
  "id": "fooid",
  "name": "response",
  "namespace": "sysadm"
 }

.. index:: runreplication, Life Preserver

.. _Start Replication:

Start Replication
=================

The "runreplication" action can be used to manually replicate the
specified dataset to the specified remote server.

**REST Request**

::

 PUT /sysadm/lifepreserver
 {
   "host" : "10.0.10.100",
   "dataset" : "mypool",
   "action" : "runreplication"
 }

**REST Response**

.. code-block:: json

 {
    "args": {
        "runreplication": {
            "dataset": "mypool",
            "host": "10.0.10.100"
        }
    }
 }

**WebSocket Request**

.. code-block:: json

 {
   "id" : "fooid",
   "name" : "lifepreserver",
   "args" : {
      "host" : "10.0.10.100",
      "dataset" : "mypool",
      "action" : "runreplication"
   },
   "namespace" : "sysadm"
 }

**WebSocket Response**

.. code-block:: json

 {
  "args": {
    "runreplication": {
      "dataset": "mypool",
      "host": "10.0.10.100"
    }
  },
  "id": "fooid",
  "name": "response",
  "namespace": "sysadm"
 }

.. index:: initreplication, Life Preserver

.. _Initialize Replication:

Initialize Replication
======================

The "initreplication" action can be used to clear the replication data
on the remote server. This is useful if a replication becomes stuck.
After running this action, issue a "runreplication" action to start a
new replication.

The "initreplication" action supports the following parameters:

+---------------+-----------------------------------------------------+
| **Parameter** | **Description**                                     |
|               |                                                     |
+===============+=====================================================+
| host          | Remote hostname or IP address.                      |
|               |                                                     |
+---------------+-----------------------------------------------------+
| dataset       | Name of local dataset or pool being replicated.     |
|               |                                                     |
+---------------+-----------------------------------------------------+

**REST Request**

::

 PUT /sysadm/lifepreserver
 {
   "dataset" : "tank1",
   "host" : "192.168.0.9",
   "action" : "initreplication"
 }

**REST Response**

.. code-block:: json

 {
    "args": {
        "initreplication": {
            "dataset": "tank1",
            "host": "192.168.0.9"
        }
    }
 }

**WebSocket Request**

.. code-block:: json

 {
   "id" : "fooid",
   "args" : {
      "host" : "192.168.0.9",
      "dataset" : "tank1",
      "action" : "initreplication"
   },
   "namespace" : "sysadm",
   "name" : "lifepreserver"
 }

**WebSocket Response**

.. code-block:: json

 {
  "args": {
    "initreplication": {
      "dataset": "tank1",
      "host": "192.168.0.9"
    }
  },
  "id": "fooid",
  "name": "response",
  "namespace": "sysadm"
 }

.. index:: settings, Life Preserver

.. _View Settings:

View Settings
=============

The "settings" action returns the system-wide settings of the Life
Preserver utility. The returned settings include the disk percentage
used at which Life Preserver will issue a warning, the level at which an
email will be sent, the email address to send notifications to, and
whether or not snapshots are taken recursively (include all child
datasets).

Run :command:`lpreserver help set` for more information about each
available setting.

**REST Request**

::

 PUT /sysadm/lifepreserver
 {
   "action" : "settings"
 }

**REST Response**

.. code-block:: json

 {
    "args": {
        "settings": {
            "diskwarn": "85%",
            "email": "WARN",
            "emailaddress": "me@mycompany.com",
            "recursive": "ON"
        }
    }
 }

**WebSocket Request**

.. code-block:: json

 {
   "id" : "fooid",
   "args" : {
      "action" : "settings"
   },
   "namespace" : "sysadm",
   "name" : "lifepreserver"
 }

**WebSocket Response**

.. code-block:: json

 {
  "args": {
    "settings": {
      "diskwarn": "85%",
      "email": "WARN",
      "emailaddress": "me@mycompany.com",
      "recursive": "ON"
    }
  },
  "id": "fooid",
  "name": "response",
  "namespace": "sysadm"
 }

.. index:: savesettings, Life Preserver

.. _Save Settings:

Save Settings
=============

The "savesettings" action can be used to modify the system-wide settings
of the Life Preserver utility. This action supports the following
parameters:

+---------------+-----------------------------------------------------+
| **Parameter** | **Description**                                     |
|               |                                                     |
+===============+=====================================================+
| duwarn        | Disk percentage (from 0-99) at which to warn of low |
|               | disk space.                                         |
+---------------+-----------------------------------------------------+
| email         | Email address to send notifications.                |
|               |                                                     |
+---------------+-----------------------------------------------------+
| emailopts     | Conditions which trigger an email notification.     |
|               | Possible values are "ALL" (every snapshot, warning  |
|               | and error),"WARN" (warnings and errors--this is the |
|               | default condition), or "ERROR" (errors only).       |
+---------------+-----------------------------------------------------+
| recursive     | Whether or not to include all child datasets in the |
|               | snapshot; possible values are "true" or "false"     |
+---------------+-----------------------------------------------------+

**REST Request**

::

 PUT /sysadm/lifepreserver
 {
   "emailopts" : "ALL",
   "duwarn" : "70",
   "recursive" : "true",
   "action" : "savesettings",
   "email" : "kris@example.org"
 }

**REST Response**

.. code-block:: json

 {
    "args": {
        "savesettings": {
            "duwarn": "70",
            "email": "kris@example.org",
            "emailopts": "ALL",
            "recursive": "true"
        }
    }
 }

**WebSocket Request**

.. code-block:: json

 {
   "args" : {
      "emailopts" : "ALL",
      "action" : "savesettings",
      "duwarn" : "70",
      "recursive" : "true",
      "email" : "kris@example.org"
   },
   "id" : "fooid",
   "namespace" : "sysadm",
   "name" : "lifepreserver"
 }

**WebSocket Response**

.. code-block:: json

 {
  "args": {
    "savesettings": {
      "duwarn": "70",
      "email": "kris@example.org",
      "emailopts": "ALL",
      "recursive": "true"
    }
  },
  "id": "fooid",
  "name": "response",
  "namespace": "sysadm"
 }
