Metadata-Version: 2.4
Name: truenas_backup_tool
Version: 0.1.1
Summary: A simple tool to fetch backups from the TrueNAS via the JSON-RPC protocol
Author-email: Stanislav Meduna <stano@meduna.org>
Project-URL: Homepage, https://github.com/numo68/truenas-backup
Project-URL: Bug Tracker, https://github.com/numo68/truenas-backup/issues
Classifier: Programming Language :: Python :: 3
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: OS Independent
Requires-Python: >=3.10
Description-Content-Type: text/x-rst
License-File: LICENSE
Requires-Dist: PyYAML
Requires-Dist: schema
Requires-Dist: prometheus-client
Requires-Dist: PyCryptodome
Requires-Dist: httpx
Dynamic: license-file

Usage
=====

**truenas-backup** is a simple tool to fetch configuration backups from
the TrueNAS installation using the JSON-RPC API.

Installation
------------

As the API client is not published as a package, you'll need to install
the dependency manually

.. code-block:: shell

   pip install git+https://github.com/truenas/api_client.git

Arguments
----------------

``-h``, ``--help``
   show the help message and exit.

``-c FILE``, ``--config FILE``
   the configuration file (default: ``~/.config/truenas-backup/config.yml``)

``-o FILE``, ``--output FILE``
   the output file. The file name can contain ``strftime`` directives. If the argument
   is specified, ``directory``, ``name`` and ``keep`` fields of the configuration
   are ignored.

Configuration file
==================

The ``truenas-backup`` needs a configuration file
(default ``~/.config/truenas-backup/config.yml``). As the file contains secrets,
take care to set reasonable permissions. The file is in
the `YAML <https://yaml.org/>`_ format.

Configuration file
------------------

.. code-block:: yaml

      truenas:
         host: truenas.local[:port]
         api_user: truenas_admin
         api_key: ...
         ssl_verify: false
         call_timeout: 20
         backup_password: ...
      output:
         directory: .
         name: "truenas-%Y%m%d-%H%M.backup"
         keep: 12

All fields except ``api_user`` and ``api_key`` are optional. The user
the API key was generated for needs to have the ``FULL_ADMIN`` role
(TrueNAS requirement).

``host`` is a hostname or an IP address, and an optional port.
Secure connection will be used.

The backup file is compressed using gzip first, then encrypted if ``backup_password``
is specified. It can be decrypted and unpacked manually using

``openssl aes-256-cbc -d -md sha512 -pbkdf2 -iter 100000 -in ... | tar tvfz -``

``name`` specifies the name of the output file. ``strftime`` directives
are allowed.

``keep`` removes all but the most recent ``*.backup`` files from the ``directory``,
that in this case has to be specified and has to be an absolute path.

``directory`` has to already exist. As the backup is not encrypted
and contains secrets the permissions should be set accordingly.


Observability
-------------

The backups done can be exported through prometheus text-file format and consumed
by the node exporter's textfile collector. If the ``metrics`` key exists, the file
is atomically populated after each backup run.

.. code-block:: yaml

    metrics:
        directory: "/var/local/lib/prom_metrics"
        suffix: "my-truenas"

``directory`` is mandatory and specifies the path of the directory passed as the
``--collector.textfile.directory`` for the ``node_exporter``. It has to already exist.
``suffix`` is optional and will be appended to the file name to distinguish metrics
files generated by different configurations. For the above configuration
the full file name will be ``/var/local/lib/prom_metrics/truenas-backup-my-truenas.prom``.
