stdin-from-command: add documentation in backup sub-command

This commit is contained in:
Enrico204 2023-08-27 10:33:46 +02:00 committed by Michael Eischer
parent 4e5caab114
commit 072b227544
1 changed files with 51 additions and 16 deletions

View File

@ -489,35 +489,70 @@ particular note are::
- file ownership and ACLs on Windows - file ownership and ACLs on Windows
- the "hidden" flag on Windows - the "hidden" flag on Windows
Reading data from a command standard output
***********************
Sometimes, it can be nice to directly save the output of a program, e.g.,
``mysqldump`` so that the SQL can later be restored. Restic supports this mode
of operation; just supply the option ``--stdin-from-command`` when using the
``backup`` action, and write the command in place of the files/directories:
.. code-block:: console
$ restic -r /srv/restic-repo backup --stdin-from-command mysqldump [...]
This command creates a new snapshot of the standard output of ``mysqldump``.
You can then use, e.g., the fuse mounting option (see below) to mount the
repository and read the file.
By default, the command's standard output is saved in a file named ``stdin``.
A different name can be specified with ``--stdin-filename``, e.g.:
.. code-block:: console
$ restic -r /srv/restic-repo backup --stdin-filename production.sql --stdin-from-command mysqldump [...]
Restic uses the command exit code to determine whether the backup succeeded. A
non-zero exit code from the command makes Restic cancel the backup.
Reading data from stdin Reading data from stdin
*********************** ***********************
Sometimes it can be nice to directly save the output of a program, e.g. If the ``--stdin-from-command`` option is insufficient, Restic supports reading
``mysqldump`` so that the SQL can later be restored. Restic supports arbitrary data from the standard input. Use the option ``--stdin`` to the
this mode of operation, just supply the option ``--stdin`` to the
``backup`` command like this: ``backup`` command like this:
.. code-block:: console .. code-block:: console
$ set -o pipefail $ restic -r /srv/restic-repo backup --stdin < bigfile.dat
$ mysqldump [...] | restic -r /srv/restic-repo backup --stdin
This creates a new snapshot of the output of ``mysqldump``. You can then This creates a new snapshot of the content of ``bigfile.dat`` (note that, in
use e.g. the fuse mounting option (see below) to mount the repository this example, you can trivially use the standard ``backup`` command by
and read the file. specifying the file path).
By default, the file name ``stdin`` is used, a different name can be As for ``--stdin-from-command``, the default file name is ``stdin``; a
specified with ``--stdin-filename``, e.g. like this: different name can be specified with ``--stdin-filename``.
**Important**: while it is possible to pipe a command output in Restic using
``--stdin``, doing so is highly discouraged as it will mask errors from the
command, leading to corrupted backups. For example, in the following code
block, if ``mysqldump`` has an error connecting to the MySQL database, Restic
backup will succeed in creating an empty backup:
.. code-block:: console .. code-block:: console
$ mysqldump [...] | restic -r /srv/restic-repo backup --stdin --stdin-filename production.sql $ # Don't do this, read the warning above
$ mysqldump [...] | restic -r /srv/restic-repo backup --stdin
The option ``pipefail`` is highly recommended so that a non-zero exit code from A simple solution is to use ``--stdin-from-command`` (see above). Shall you
one of the programs in the pipe (e.g. ``mysqldump`` here) makes the whole chain still need to use the ``--stdin`` flag, you must use the option ``pipefail``
return a non-zero exit code. Refer to the `Use the Unofficial Bash Strict Mode (so that a non-zero exit code from one of the programs in the pipe makes the
<http://redsymbol.net/articles/unofficial-bash-strict-mode/>`__ for more whole chain return a non-zero exit code) and you must check the exit code of
details on this. the pipe and act accordingly (e.g., remove the last backup). Refer to the
`Use the Unofficial Bash Strict Mode <http://redsymbol.net/articles/unofficial-bash-strict-mode/>`__
for more details on this.
Tags for backup Tags for backup