github.com/advanderveer/restic@v0.8.1-0.20171209104529-42a8c19aaea6/doc/040_backup.rst (about)

     1  ..
     2    Normally, there are no heading levels assigned to certain characters as the structure is
     3    determined from the succession of headings. However, this convention is used in Python’s
     4    Style Guide for documenting which you may follow:
     5  
     6    # with overline, for parts
     7    * for chapters
     8    = for sections
     9    - for subsections
    10    ^ for subsubsections
    11    " for paragraphs
    12  
    13  ##########
    14  Backing up
    15  ##########
    16  
    17  Now we're ready to backup some data. The contents of a directory at a
    18  specific point in time is called a "snapshot" in restic. Run the
    19  following command and enter the repository password you chose above
    20  again:
    21  
    22  .. code-block:: console
    23  
    24      $ restic -r /tmp/backup backup ~/work
    25      enter password for repository:
    26      scan [/home/user/work]
    27      scanned 764 directories, 1816 files in 0:00
    28      [0:29] 100.00%  54.732 MiB/s  1.582 GiB / 1.582 GiB  2580 / 2580 items  0 errors  ETA 0:00
    29      duration: 0:29, 54.47MiB/s
    30      snapshot 40dc1520 saved
    31  
    32  As you can see, restic created a backup of the directory and was pretty
    33  fast! The specific snapshot just created is identified by a sequence of
    34  hexadecimal characters, ``40dc1520`` in this case.
    35  
    36  If you run the command again, restic will create another snapshot of
    37  your data, but this time it's even faster. This is de-duplication at
    38  work!
    39  
    40  .. code-block:: console
    41  
    42      $ restic -r /tmp/backup backup ~/work
    43      enter password for repository:
    44      using parent snapshot 40dc1520aa6a07b7b3ae561786770a01951245d2367241e71e9485f18ae8228c
    45      scan [/home/user/work]
    46      scanned 764 directories, 1816 files in 0:00
    47      [0:00] 100.00%  0B/s  1.582 GiB / 1.582 GiB  2580 / 2580 items  0 errors  ETA 0:00
    48      duration: 0:00, 6572.38MiB/s
    49      snapshot 79766175 saved
    50  
    51  You can even backup individual files in the same repository.
    52  
    53  .. code-block:: console
    54  
    55      $ restic -r /tmp/backup backup ~/work.txt
    56      scan [/home/user/work.txt]
    57      scanned 0 directories, 1 files in 0:00
    58      [0:00] 100.00%  0B/s  220B / 220B  1 / 1 items  0 errors  ETA 0:00
    59      duration: 0:00, 0.03MiB/s
    60      snapshot 31f7bd63 saved
    61  
    62  In fact several hosts may use the same repository to backup directories
    63  and files leading to a greater de-duplication.
    64  
    65  Please be aware that when you backup different directories (or the
    66  directories to be saved have a variable name component like a
    67  time/date), restic always needs to read all files and only afterwards
    68  can compute which parts of the files need to be saved. When you backup
    69  the same directory again (maybe with new or changed files) restic will
    70  find the old snapshot in the repo and by default only reads those files
    71  that are new or have been modified since the last snapshot. This is
    72  decided based on the modify date of the file in the file system.
    73  
    74  Now is a good time to run ``restic check`` to verify that all data
    75  is properly stored in the repository. You should run this command regularly
    76  to make sure the internal structure of the repository is free of errors.
    77  
    78  You can exclude folders and files by specifying exclude-patterns. Either
    79  specify them with multiple ``--exclude``'s or one ``--exclude-file``
    80  
    81  .. code-block:: console
    82  
    83      $ cat exclude
    84      # exclude go-files
    85      *.go
    86      # exclude foo/x/y/z/bar foo/x/bar foo/bar
    87      foo/**/bar
    88      $ restic -r /tmp/backup backup ~/work --exclude=*.c --exclude-file=exclude
    89  
    90  Patterns use `filepath.Glob <https://golang.org/pkg/path/filepath/#Glob>`__ internally,
    91  see `filepath.Match <https://golang.org/pkg/path/filepath/#Match>`__ for syntax.
    92  Additionally ``**`` excludes arbitrary subdirectories.
    93  Environment-variables in exclude-files are expanded with
    94  `os.ExpandEnv <https://golang.org/pkg/os/#ExpandEnv>`__.
    95  
    96  By specifying the option ``--one-file-system`` you can instruct restic
    97  to only backup files from the file systems the initially specified files
    98  or directories reside on. For example, calling restic like this won't
    99  backup ``/sys`` or ``/dev`` on a Linux system:
   100  
   101  .. code-block:: console
   102  
   103      $ restic -r /tmp/backup backup --one-file-system /
   104  
   105  By using the ``--files-from`` option you can read the files you want to
   106  backup from a file. This is especially useful if a lot of files have to
   107  be backed up that are not in the same folder or are maybe pre-filtered
   108  by other software.
   109  
   110  or example maybe you want to backup files that have a certain filename
   111  in them:
   112  
   113  .. code-block:: console
   114  
   115      $ find /tmp/somefiles | grep 'PATTERN' > /tmp/files_to_backup
   116  
   117  You can then use restic to backup the filtered files:
   118  
   119  .. code-block:: console
   120  
   121      $ restic -r /tmp/backup backup --files-from /tmp/files_to_backup
   122  
   123  Incidentally you can also combine ``--files-from`` with the normal files
   124  args:
   125  
   126  .. code-block:: console
   127  
   128      $ restic -r /tmp/backup backup --files-from /tmp/files_to_backup /tmp/some_additional_file
   129  
   130  Comparing Snapshots
   131  *******************
   132  
   133  Restic has a `diff` command which shows the difference between two snapshots
   134  and displays a small statistic, just pass the command two snapshot IDs:
   135  
   136  .. code-block:: console
   137  
   138      $ restic -r /tmp/backup diff 5845b002 2ab627a6
   139      password is correct
   140      comparing snapshot ea657ce5 to 2ab627a6:
   141  
   142       C   /restic/cmd_diff.go
   143      +    /restic/foo
   144       C   /restic/restic
   145  
   146      Files:           0 new,     0 removed,     2 changed
   147      Dirs:            1 new,     0 removed
   148      Others:          0 new,     0 removed
   149      Data Blobs:     14 new,    15 removed
   150      Tree Blobs:      2 new,     1 removed
   151        Added:   16.403 MiB
   152        Removed: 16.402 MiB
   153  
   154  
   155  Backing up special items and metadata
   156  *************************************
   157  
   158  **Symlinks** are archived as symlinks, ``restic`` does not follow them.
   159  When you restore, you get the same symlink again, with the same link target
   160  and the same timestamps.
   161  
   162  If there is a **bind-mount** below a directory that is to be saved, restic descends into it.
   163  
   164  **Device files** are saved and restored as device files. This means that e.g. ``/dev/sda`` is
   165  archived as a block device file and restored as such. This also means that the content of the
   166  corresponding disk is not read, at least not from the device file.
   167  
   168  By default, restic does not save the access time (atime) for any files or other
   169  items, since it is not possible to reliably disable updating the access time by
   170  restic itself. This means that for each new backup a lot of metadata is
   171  written, and the next backup needs to write new metadata again. If you really
   172  want to save the access time for files and directories, you can pass the
   173  ``--with-atime`` option to the ``backup`` command.
   174  
   175  Reading data from stdin
   176  ***********************
   177  
   178  Sometimes it can be nice to directly save the output of a program, e.g.
   179  ``mysqldump`` so that the SQL can later be restored. Restic supports
   180  this mode of operation, just supply the option ``--stdin`` to the
   181  ``backup`` command like this:
   182  
   183  .. code-block:: console
   184  
   185      $ mysqldump [...] | restic -r /tmp/backup backup --stdin
   186  
   187  This creates a new snapshot of the output of ``mysqldump``. You can then
   188  use e.g. the fuse mounting option (see below) to mount the repository
   189  and read the file.
   190  
   191  By default, the file name ``stdin`` is used, a different name can be
   192  specified with ``--stdin-filename``, e.g. like this:
   193  
   194  .. code-block:: console
   195  
   196      $ mysqldump [...] | restic -r /tmp/backup backup --stdin --stdin-filename production.sql
   197  
   198  Tags for backup
   199  ***************
   200  
   201  Snapshots can have one or more tags, short strings which add identifying
   202  information. Just specify the tags for a snapshot one by one with ``--tag``:
   203  
   204  .. code-block:: console
   205  
   206      $ restic -r /tmp/backup backup --tag projectX --tag foo --tag bar ~/work
   207      [...]
   208  
   209  The tags can later be used to keep (or forget) snapshots with the ``forget``
   210  command. The command ``tag`` can be used to modify tags on an existing
   211  snapshot.