Bump version for release.

NEWS

@@ -1,3 +1,12 @@
+1.5.1
+ * #289: Tired of looking up the latest successful archive name in order to pass it to borgmatic
+   actions? Me too. Now you can specify "--archive latest" to all actions that accept an archive
+   flag.
+ * #290: Fix the "--stats" and "--files" flags so that they yield output at verbosity 0.
+ * Reduce the default verbosity of borgmatic logs sent to Healthchecks monitoring hook. Now, it's
+   warnings and errors only. You can increase the verbosity via the "--monitoring-verbosity" flag.
+ * Add security policy documentation in SECURITY.md.
+
 1.5.0
  * #245: Monitor backups with PagerDuty hook integration. See the documentation for more
    information: https://torsion.org/borgmatic/docs/how-to/monitor-your-backups/#pagerduty-hook

README.md

@@ -119,7 +119,12 @@ If you'd like to chat with borgmatic developers or users, head on over to the
 href="https://webchat.freenode.net/?channels=borgmatic">web chat</a> or a
 native <a href="irc://chat.freenode.net:6697">IRC client</a>.
 
-Other questions or comments? Contact <mailto:witten@torsion.org>.
+Also see the [security
+policy](https://torsion.org/borgmatic/docs/security-policy/) for any security
+issues.
+
+Other questions or comments? Contact
+[witten@torsion.org](mailto:witten@torsion.org).
 
 
 ### Contributing

SECURITY.md

@@ -0,0 +1,19 @@
+---
+title: Security policy
+permalink: security-policy/index.html
+---
+
+## Supported versions
+
+While we want to hear about security vulnerabilities in all versions of
+borgmatic, security fixes will only be made to the most recently released
+version. It's not practical for our small volunteer effort to maintain
+multiple different release branches and put out separate security patches for
+each.
+
+## Reporting a vulnerability
+
+If you find a security vulnerability, please [file a
+ticket](https://torsion.org/borgmatic/#issues) or [send email
+directly](mailto:witten@torsion.org) as appropriate. You should expect to hear
+back within a few days at most, and generally sooner.

borgmatic/borg/list.py

@@ -11,6 +11,42 @@ logger = logging.getLogger(__name__)
 BORG_EXCLUDE_CHECKPOINTS_GLOB = '*[0123456789]'
 
 
+def resolve_archive_name(repository, archive, storage_config, local_path='borg', remote_path=None):
+    '''
+    Given a local or remote repository path, an archive name, a storage config dict, a local Borg
+    path, and a remote Borg path, simply return the archive name. But if the archive name is
+    "latest", then instead introspect the repository for the latest successful (non-checkpoint)
+    archive, and return its name.
+
+    Raise ValueError if "latest" is given but there are no archives in the repository.
+    '''
+    if archive != "latest":
+        return archive
+
+    lock_wait = storage_config.get('lock_wait', None)
+
+    full_command = (
+        (local_path, 'list')
+        + (('--info',) if logger.getEffectiveLevel() == logging.INFO else ())
+        + (('--debug', '--show-rc') if logger.isEnabledFor(logging.DEBUG) else ())
+        + make_flags('remote-path', remote_path)
+        + make_flags('lock-wait', lock_wait)
+        + make_flags('glob-archives', BORG_EXCLUDE_CHECKPOINTS_GLOB)
+        + make_flags('last', 1)
+        + ('--short', repository)
+    )
+
+    output = execute_command(full_command, output_log_level=None, error_on_warnings=False)
+    try:
+        latest_archive = output.strip().splitlines()[-1]
+    except IndexError:
+        raise ValueError('No archives found in the repository')
+
+    logger.debug('{}: Latest archive is {}'.format(repository, latest_archive))
+
+    return latest_archive
+
+
 def list_archives(repository, storage_config, list_arguments, local_path='borg', remote_path=None):
     '''
     Given a local or remote repository path, a storage config dict, and the arguments to the list

borgmatic/commands/arguments.py

@@ -163,7 +163,7 @@ def parse_arguments(*unparsed_arguments):
         '--monitoring-verbosity',
         type=int,
         choices=range(-1, 3),
-        default=1,
+        default=0,
         help='Log verbose progress to monitoring integrations that support logging (from only errors to very verbose: -1, 0, 1, or 2)',
     )
     global_group.add_argument(
@@ -323,7 +323,9 @@ def parse_arguments(*unparsed_arguments):
         '--repository',
         help='Path of repository to extract, defaults to the configured repository if there is only one',
     )
-    extract_group.add_argument('--archive', help='Name of archive to extract', required=True)
+    extract_group.add_argument(
+        '--archive', help='Name of archive to extract (or "latest")', required=True
+    )
     extract_group.add_argument(
         '--path',
         '--restore-path',
@@ -361,7 +363,7 @@ def parse_arguments(*unparsed_arguments):
         '--repository',
         help='Path of repository to use, defaults to the configured repository if there is only one',
     )
-    mount_group.add_argument('--archive', help='Name of archive to mount')
+    mount_group.add_argument('--archive', help='Name of archive to mount (or "latest")')
     mount_group.add_argument(
         '--mount-point',
         metavar='PATH',
@@ -415,7 +417,9 @@ def parse_arguments(*unparsed_arguments):
         '--repository',
         help='Path of repository to restore from, defaults to the configured repository if there is only one',
     )
-    restore_group.add_argument('--archive', help='Name of archive to restore from', required=True)
+    restore_group.add_argument(
+        '--archive', help='Name of archive to restore from (or "latest")', required=True
+    )
     restore_group.add_argument(
         '--database',
         metavar='NAME',
@@ -446,7 +450,7 @@ def parse_arguments(*unparsed_arguments):
         '--repository',
         help='Path of repository to list, defaults to the configured repository if there is only one',
     )
-    list_group.add_argument('--archive', help='Name of archive to list')
+    list_group.add_argument('--archive', help='Name of archive to list (or "latest")')
     list_group.add_argument(
         '--path',
         metavar='PATH',
@@ -508,7 +512,7 @@ def parse_arguments(*unparsed_arguments):
         '--repository',
         help='Path of repository to show info for, defaults to the configured repository if there is only one',
     )
-    info_group.add_argument('--archive', help='Name of archive to show info for')
+    info_group.add_argument('--archive', help='Name of archive to show info for (or "latest")')
     info_group.add_argument(
         '--json', dest='json', default=False, action='store_true', help='Output results as JSON'
     )

borgmatic/commands/borgmatic.py

@@ -1,4 +1,5 @@
 import collections
+import copy
 import json
 import logging
 import os
@@ -297,7 +298,9 @@ def run_actions(
             borg_extract.extract_archive(
                 global_arguments.dry_run,
                 repository,
-                arguments['extract'].archive,
+                borg_list.resolve_archive_name(
+                    repository, arguments['extract'].archive, storage, local_path, remote_path
+                ),
                 arguments['extract'].paths,
                 location,
                 storage,
@@ -319,7 +322,9 @@ def run_actions(
 
             borg_mount.mount_archive(
                 repository,
-                arguments['mount'].archive,
+                borg_list.resolve_archive_name(
+                    repository, arguments['mount'].archive, storage, local_path, remote_path
+                ),
                 arguments['mount'].mount_point,
                 arguments['mount'].paths,
                 arguments['mount'].foreground,
@@ -355,7 +360,9 @@ def run_actions(
             borg_extract.extract_archive(
                 global_arguments.dry_run,
                 repository,
-                arguments['restore'].archive,
+                borg_list.resolve_archive_name(
+                    repository, arguments['restore'].archive, storage, local_path, remote_path
+                ),
                 dump.convert_glob_patterns_to_borg_patterns(
                     dump.flatten_dump_patterns(dump_patterns, restore_names)
                 ),
@@ -395,12 +402,16 @@ def run_actions(
         if arguments['list'].repository is None or validate.repositories_match(
             repository, arguments['list'].repository
         ):
-            if not arguments['list'].json:
+            list_arguments = copy.copy(arguments['list'])
+            if not list_arguments.json:
                 logger.warning('{}: Listing archives'.format(repository))
+            list_arguments.archive = borg_list.resolve_archive_name(
+                repository, list_arguments.archive, storage, local_path, remote_path
+            )
             json_output = borg_list.list_archives(
                 repository,
                 storage,
-                list_arguments=arguments['list'],
+                list_arguments=list_arguments,
                 local_path=local_path,
                 remote_path=remote_path,
             )
@@ -410,12 +421,16 @@ def run_actions(
         if arguments['info'].repository is None or validate.repositories_match(
             repository, arguments['info'].repository
         ):
-            if not arguments['info'].json:
+            info_arguments = copy.copy(arguments['info'])
+            if not info_arguments.json:
                 logger.warning('{}: Displaying summary info for archives'.format(repository))
+            info_arguments.archive = borg_list.resolve_archive_name(
+                repository, info_arguments.archive, storage, local_path, remote_path
+            )
             json_output = borg_info.display_archives_info(
                 repository,
                 storage,
-                info_arguments=arguments['info'],
+                info_arguments=info_arguments,
                 local_path=local_path,
                 remote_path=remote_path,
             )

docs/Dockerfile

@@ -1,4 +1,4 @@
-FROM python:3.7.4-alpine3.10 as borgmatic
+FROM python:3.8.1-alpine3.11 as borgmatic
 
 COPY . /app
 RUN pip install --no-cache /app && generate-borgmatic-config && chmod +r /etc/borgmatic/config.yaml
@@ -7,7 +7,7 @@ RUN borgmatic --help > /command-line.txt \
            echo -e "\n--------------------------------------------------------------------------------\n" >> /command-line.txt \
            && borgmatic "$action" --help >> /command-line.txt; done
 
-FROM node:12.10.0-alpine as html
+FROM node:13.7.0-alpine as html
 
 ARG ENVIRONMENT=production
 

docs/SECURITY.md

@@ -0,0 +1,19 @@
+---
+title: Security policy
+permalink: security-policy/index.html
+---
+
+## Supported versions
+
+While we want to hear about security vulnerabilities in all versions of
+borgmatic, security fixes will only be made to the most recently released
+version. It's not practical for our small volunteer effort to maintain
+multiple different release branches and put out separate security patches for
+each.
+
+## Reporting a vulnerability
+
+If you find a security vulnerability, please [file a
+ticket](https://torsion.org/borgmatic/#issues) or [send email
+directly](mailto:witten@torsion.org) as appropriate. You should expect to hear
+back within a few days at most, and generally sooner.

docs/how-to/backup-to-a-removable-drive-or-an-intermittent-server.md

@@ -10,7 +10,7 @@ buddy's sometimes-online server for that extra level of redundancy.
 
 But if you run borgmatic and your hard drive isn't plugged in, or your buddy's
 server is offline, then you'll get an annoying error message and the overall
-borgmatic run will fail (even if individual repositories complete just fine).
+borgmatic run will fail (even if individual repositories still complete).
 
 So what if you want borgmatic to swallow the error of a missing drive
 or an offline server, and continue trucking along? That's where the concept of
@@ -96,7 +96,7 @@ There are some caveats you should be aware of with this feature.
    a test to make sure that individual source directories are mounted and
    available. Use your imagination!
  * The soft failure feature also works for `before_prune`, `after_prune`,
-   `before_check`, and `after_check` hooks. However it is not implemented for
+   `before_check`, and `after_check` hooks. But it is not implemented for
    `before_everything` or `after_everything`.
 
 ## Related documentation

docs/how-to/backup-your-databases.md

@@ -112,6 +112,12 @@ borgmatic restore --archive host-2019-01-02T04:06:07.080910
 
 (No borgmatic `restore` action? Upgrade borgmatic!)
 
+With newer versions of borgmatic, you can simplify this to:
+
+```bash
+borgmatic restore --archive latest
+```
+
 The `--archive` value is the name of the archive to restore from. This
 restores all databases dumps that borgmatic originally backed up to that
 archive.

docs/how-to/extract-a-backup.md

@@ -31,6 +31,12 @@ borgmatic extract --archive host-2019-01-02T04:06:07.080910
 (No borgmatic `extract` action? Try the old-style `--extract`, or upgrade
 borgmatic!)
 
+With newer versions of borgmatic, you can simplify this to:
+
+```bash
+borgmatic extract --archive latest
+```
+
 The `--archive` value is the name of the archive to extract. This extracts the
 entire contents of the archive to the current directory, so make sure you're
 in the right place before running the command.
@@ -106,6 +112,12 @@ Omit the `--archive` flag to mount all archives (lazy-loaded):
 borgmatic mount --mount-point /mnt
 ```
 
+Or use the "latest" value for the archive to mount the latest successful archive:
+
+```bash
+borgmatic mount --archive latest --mount-point /mnt
+```
+
 If you'd like to restrict the mounted filesystem to only particular paths from
 your archive, use the `--path` flag, similar to the `extract` action above.
 For instance:

docs/how-to/monitor-your-backups.md

@@ -203,9 +203,9 @@ or it doesn't hear from borgmatic for a certain period of time.
 
 ## PagerDuty hook
 
-[PagerDuty](https://cronhub.io/) provides incident monitoring and alerting,
-and borgmatic has built-in integration with it. Once you create a PagerDuty
-account and <a
+[PagerDuty](https://www.pagerduty.com/) provides incident monitoring and
+alerting, and borgmatic has built-in integration with it. Once you create a
+PagerDuty account and <a
 href="https://support.pagerduty.com/docs/services-and-integrations">service</a>
 on their site, all you need to do is configure borgmatic with the unique
 "Integration Key" for your service. Here's an example:
@@ -261,6 +261,18 @@ multiple different hosts into a single repository, then you'll need to get
 fancier with your archive listing. See `borg list --help` for more flags.
 
 
+### Latest backups
+
+All borgmatic actions that accept an "--archive" flag allow you to specify an
+archive name of "latest". This lets you get the latest successful archive
+without having to first run "borgmatic list" manually, which can be handy in
+automated scripts. Here's an example:
+
+```bash
+borgmatic info --archive latest
+```
+
+
 ## Related documentation
 
  * [Set up backups with borgmatic](https://torsion.org/borgmatic/docs/how-to/set-up-backups/)

scripts/run-full-tests

@@ -10,8 +10,8 @@
 
 set -e
 
-python -m pip install --upgrade pip==19.3.1
-pip install tox==3.14.1
+python -m pip install --upgrade pip==20.0.2
+pip install tox==3.14.3
 export COVERAGE_FILE=/tmp/.coverage
 tox --workdir /tmp/.tox
 apk add --no-cache borgbackup postgresql-client mariadb-client

setup.py

@@ -1,6 +1,6 @@
 from setuptools import find_packages, setup
 
-VERSION = '1.5.0'
+VERSION = '1.5.1'
 
 
 setup(

tests/unit/borg/test_list.py

@@ -7,6 +7,110 @@ from borgmatic.borg import list as module
 
 from ..test_verbosity import insert_logging_mock
 
+BORG_LIST_LATEST_ARGUMENTS = (
+    '--glob-archives',
+    module.BORG_EXCLUDE_CHECKPOINTS_GLOB,
+    '--last',
+    '1',
+    '--short',
+    'repo',
+)
+
+
+def test_resolve_archive_name_passes_through_non_latest_archive_name():
+    archive = 'myhost-2030-01-01T14:41:17.647620'
+
+    assert module.resolve_archive_name('repo', archive, storage_config={}) == archive
+
+
+def test_resolve_archive_name_calls_borg_with_parameters():
+    expected_archive = 'archive-name'
+    flexmock(module).should_receive('execute_command').with_args(
+        ('borg', 'list') + BORG_LIST_LATEST_ARGUMENTS,
+        output_log_level=None,
+        error_on_warnings=False,
+    ).and_return(expected_archive + '\n')
+
+    assert module.resolve_archive_name('repo', 'latest', storage_config={}) == expected_archive
+
+
+def test_resolve_archive_name_with_log_info_calls_borg_with_info_parameter():
+    expected_archive = 'archive-name'
+    flexmock(module).should_receive('execute_command').with_args(
+        ('borg', 'list', '--info') + BORG_LIST_LATEST_ARGUMENTS,
+        output_log_level=None,
+        error_on_warnings=False,
+    ).and_return(expected_archive + '\n')
+    insert_logging_mock(logging.INFO)
+
+    assert module.resolve_archive_name('repo', 'latest', storage_config={}) == expected_archive
+
+
+def test_resolve_archive_name_with_log_debug_calls_borg_with_debug_parameter():
+    expected_archive = 'archive-name'
+    flexmock(module).should_receive('execute_command').with_args(
+        ('borg', 'list', '--debug', '--show-rc') + BORG_LIST_LATEST_ARGUMENTS,
+        output_log_level=None,
+        error_on_warnings=False,
+    ).and_return(expected_archive + '\n')
+    insert_logging_mock(logging.DEBUG)
+
+    assert module.resolve_archive_name('repo', 'latest', storage_config={}) == expected_archive
+
+
+def test_resolve_archive_name_with_local_path_calls_borg_via_local_path():
+    expected_archive = 'archive-name'
+    flexmock(module).should_receive('execute_command').with_args(
+        ('borg1', 'list') + BORG_LIST_LATEST_ARGUMENTS,
+        output_log_level=None,
+        error_on_warnings=False,
+    ).and_return(expected_archive + '\n')
+
+    assert (
+        module.resolve_archive_name('repo', 'latest', storage_config={}, local_path='borg1')
+        == expected_archive
+    )
+
+
+def test_resolve_archive_name_with_remote_path_calls_borg_with_remote_path_parameters():
+    expected_archive = 'archive-name'
+    flexmock(module).should_receive('execute_command').with_args(
+        ('borg', 'list', '--remote-path', 'borg1') + BORG_LIST_LATEST_ARGUMENTS,
+        output_log_level=None,
+        error_on_warnings=False,
+    ).and_return(expected_archive + '\n')
+
+    assert (
+        module.resolve_archive_name('repo', 'latest', storage_config={}, remote_path='borg1')
+        == expected_archive
+    )
+
+
+def test_resolve_archive_name_without_archives_raises():
+    flexmock(module).should_receive('execute_command').with_args(
+        ('borg', 'list') + BORG_LIST_LATEST_ARGUMENTS,
+        output_log_level=None,
+        error_on_warnings=False,
+    ).and_return('')
+
+    with pytest.raises(ValueError):
+        module.resolve_archive_name('repo', 'latest', storage_config={})
+
+
+def test_resolve_archive_name_with_lock_wait_calls_borg_with_lock_wait_parameters():
+    expected_archive = 'archive-name'
+
+    flexmock(module).should_receive('execute_command').with_args(
+        ('borg', 'list', '--lock-wait', 'okay') + BORG_LIST_LATEST_ARGUMENTS,
+        output_log_level=None,
+        error_on_warnings=False,
+    ).and_return(expected_archive + '\n')
+
+    assert (
+        module.resolve_archive_name('repo', 'latest', storage_config={'lock_wait': 'okay'})
+        == expected_archive
+    )
+
 
 def test_list_archives_calls_borg_with_parameters():
     flexmock(module).should_receive('execute_command').with_args(