From a58d17650066721942f652d4846eaf870ac8eb48 Mon Sep 17 00:00:00 2001 From: Michael Eischer Date: Wed, 3 Dec 2025 18:33:00 +0100 Subject: [PATCH 1/3] docs: clarify that parameter tuning applies to all commands --- ...parameters.rst => 047_tuning_parameters.rst} | 17 +++++++++-------- doc/index.rst | 2 +- 2 files changed, 10 insertions(+), 9 deletions(-) rename doc/{047_tuning_backup_parameters.rst => 047_tuning_parameters.rst} (92%) diff --git a/doc/047_tuning_backup_parameters.rst b/doc/047_tuning_parameters.rst similarity index 92% rename from doc/047_tuning_backup_parameters.rst rename to doc/047_tuning_parameters.rst index f1b89a7eb..eba958211 100644 --- a/doc/047_tuning_backup_parameters.rst +++ b/doc/047_tuning_parameters.rst @@ -9,14 +9,14 @@ ^ for subsubsections " for paragraphs -######################## -Tuning Backup Parameters -######################## +################# +Tuning Parameters +################# -Restic offers a few parameters that allow tuning the backup. The default values should -work well in general although specific use cases can benefit from different non-default -values. As the restic commands evolve over time, the optimal value for each parameter -can also change across restic versions. +Restic offers a few parameters that allow tuning the backup and other operations. +The default values should work well in general although specific use cases can +benefit from different non-default values. As the restic commands evolve over +time, the optimal value for each parameter can also change across restic versions. Disabling Backup Progress Estimation @@ -99,7 +99,8 @@ Swift and some Google Drive Team accounts, where there are hard limits on the to number of files. Larger pack sizes can also improve the backup speed for a repository stored on a local HDD. This can be achieved by either using the ``--pack-size`` option or defining the ``$RESTIC_PACK_SIZE`` environment variable, using an integer value for the -pack size in MiB. Restic currently defaults to a 16 MiB pack size. +pack size in MiB. Restic currently defaults to a 16 MiB pack size. Note that this +setting should be specified for each restic command that modifies the repository. The side effect of increasing the pack size is requiring more disk space for temporary pack files created before uploading. The space must be available in the system default temp diff --git a/doc/index.rst b/doc/index.rst index 8b72dcf58..ecfdabaa8 100644 --- a/doc/index.rst +++ b/doc/index.rst @@ -9,7 +9,7 @@ Restic Documentation 030_preparing_a_new_repo 040_backup 045_working_with_repos - 047_tuning_backup_parameters + 047_tuning_parameters 050_restore 060_forget 070_encryption From 7a3b06f78a99354363d0510519fa59666a0c096d Mon Sep 17 00:00:00 2001 From: Michael Eischer Date: Wed, 3 Dec 2025 18:38:36 +0100 Subject: [PATCH 2/3] docs: move environment variables to the scripting section --- doc/040_backup.rst | 85 +------------------------------------- doc/075_scripting.rst | 95 ++++++++++++++++++++++++++++++++++++++++++- 2 files changed, 94 insertions(+), 86 deletions(-) diff --git a/doc/040_backup.rst b/doc/040_backup.rst index 3abd2aeb9..9504a223d 100644 --- a/doc/040_backup.rst +++ b/doc/040_backup.rst @@ -716,87 +716,4 @@ Environment Variables ********************* In addition to command-line options, restic supports passing various options in -environment variables. The following lists these environment variables: - -.. code-block:: console - - RESTIC_REPOSITORY_FILE Name of file containing the repository location (replaces --repository-file) - RESTIC_REPOSITORY Location of repository (replaces -r) - RESTIC_PASSWORD_FILE Location of password file (replaces --password-file) - RESTIC_PASSWORD The actual password for the repository - RESTIC_PASSWORD_COMMAND Command printing the password for the repository to stdout - RESTIC_KEY_HINT ID of key to try decrypting first, before other keys - RESTIC_CACERT Location(s) of certificate file(s), comma separated if multiple (replaces --cacert) - RESTIC_TLS_CLIENT_CERT Location of TLS client certificate and private key (replaces --tls-client-cert) - RESTIC_CACHE_DIR Location of the cache directory - RESTIC_COMPRESSION Compression mode (only available for repository format version 2) - RESTIC_HOST Only consider snapshots for this host / Set the hostname for the snapshot manually (replaces --host) - RESTIC_PROGRESS_FPS Frames per second by which the progress bar is updated - RESTIC_PACK_SIZE Target size for pack files - RESTIC_READ_CONCURRENCY Concurrency for file reads - - TMPDIR Location for temporary files (except Windows) - TMP Location for temporary files (only Windows) - - AWS_ACCESS_KEY_ID Amazon S3 access key ID - AWS_SECRET_ACCESS_KEY Amazon S3 secret access key - AWS_SESSION_TOKEN Amazon S3 temporary session token - AWS_DEFAULT_REGION Amazon S3 default region - AWS_PROFILE Amazon credentials profile (alternative to specifying key and region) - AWS_SHARED_CREDENTIALS_FILE Location of the AWS CLI shared credentials file (default: ~/.aws/credentials) - RESTIC_AWS_ASSUME_ROLE_ARN Amazon IAM Role ARN to assume using discovered credentials - RESTIC_AWS_ASSUME_ROLE_SESSION_NAME Session Name to use with the role assumption - RESTIC_AWS_ASSUME_ROLE_EXTERNAL_ID External ID to use with the role assumption - RESTIC_AWS_ASSUME_ROLE_POLICY Inline Amazion IAM session policy - RESTIC_AWS_ASSUME_ROLE_REGION Region to use for IAM calls for the role assumption (default: us-east-1) - RESTIC_AWS_ASSUME_ROLE_STS_ENDPOINT URL to the STS endpoint (default is determined based on RESTIC_AWS_ASSUME_ROLE_REGION). You generally do not need to set this, advanced use only. - - AZURE_ACCOUNT_NAME Account name for Azure - AZURE_ACCOUNT_KEY Account key for Azure - AZURE_ACCOUNT_SAS Shared access signatures (SAS) for Azure - AZURE_ENDPOINT_SUFFIX Endpoint suffix for Azure Storage (default: core.windows.net) - AZURE_FORCE_CLI_CREDENTIAL Force the use of Azure CLI credentials for authentication - - B2_ACCOUNT_ID Account ID or applicationKeyId for Backblaze B2 - B2_ACCOUNT_KEY Account Key or applicationKey for Backblaze B2 - - GOOGLE_PROJECT_ID Project ID for Google Cloud Storage - GOOGLE_APPLICATION_CREDENTIALS Application Credentials for Google Cloud Storage (e.g. $HOME/.config/gs-secret-restic-key.json) - - OS_AUTH_URL Auth URL for keystone authentication - OS_REGION_NAME Region name for keystone authentication - OS_USERNAME Username for keystone authentication - OS_USER_ID User ID for keystone v3 authentication - OS_PASSWORD Password for keystone authentication - OS_TENANT_ID Tenant ID for keystone v2 authentication - OS_TENANT_NAME Tenant name for keystone v2 authentication - - OS_USER_DOMAIN_NAME User domain name for keystone authentication - OS_USER_DOMAIN_ID User domain ID for keystone v3 authentication - OS_PROJECT_NAME Project name for keystone authentication - OS_PROJECT_DOMAIN_NAME Project domain name for keystone authentication - OS_PROJECT_DOMAIN_ID Project domain ID for keystone v3 authentication - OS_TRUST_ID Trust ID for keystone v3 authentication - - OS_APPLICATION_CREDENTIAL_ID Application Credential ID (keystone v3) - OS_APPLICATION_CREDENTIAL_NAME Application Credential Name (keystone v3) - OS_APPLICATION_CREDENTIAL_SECRET Application Credential Secret (keystone v3) - - OS_STORAGE_URL Storage URL for token authentication - OS_AUTH_TOKEN Auth token for token authentication - - RCLONE_BWLIMIT rclone bandwidth limit - - RESTIC_REST_USERNAME Restic REST Server username - RESTIC_REST_PASSWORD Restic REST Server password - - ST_AUTH Auth URL for keystone v1 authentication - ST_USER Username for keystone v1 authentication - ST_KEY Password for keystone v1 authentication - -See :ref:`caching` for the rules concerning cache locations when -``RESTIC_CACHE_DIR`` is not set. - -The external programs that restic may execute include ``rclone`` (for rclone -backends) and ``ssh`` (for the SFTP backend). These may respond to further -environment variables and configuration files; see their respective manuals. +environment variables. See :ref:`environment-variables` for a list. diff --git a/doc/075_scripting.rst b/doc/075_scripting.rst index 869f9d7a1..299ea05ef 100644 --- a/doc/075_scripting.rst +++ b/doc/075_scripting.rst @@ -14,8 +14,99 @@ Scripting ######################### -This is a list of how certain tasks may be accomplished when you use -restic via scripts. +This section provides an overview of available environment variables and how +certain tasks may be accomplished when you use restic via scripts. + +.. _environment-variables: + +Environment Variables +********************* + +In addition to command-line options, restic supports passing various options in +environment variables. The following lists these environment variables: + +.. code-block:: console + + RESTIC_REPOSITORY_FILE Name of file containing the repository location (replaces --repository-file) + RESTIC_REPOSITORY Location of repository (replaces -r) + RESTIC_PASSWORD_FILE Location of password file (replaces --password-file) + RESTIC_PASSWORD The actual password for the repository + RESTIC_PASSWORD_COMMAND Command printing the password for the repository to stdout + RESTIC_KEY_HINT ID of key to try decrypting first, before other keys + RESTIC_CACERT Location(s) of certificate file(s), comma separated if multiple (replaces --cacert) + RESTIC_TLS_CLIENT_CERT Location of TLS client certificate and private key (replaces --tls-client-cert) + RESTIC_CACHE_DIR Location of the cache directory + RESTIC_COMPRESSION Compression mode (only available for repository format version 2) + RESTIC_HOST Only consider snapshots for this host / Set the hostname for the snapshot manually (replaces --host) + RESTIC_PROGRESS_FPS Frames per second by which the progress bar is updated + RESTIC_PACK_SIZE Target size for pack files + RESTIC_READ_CONCURRENCY Concurrency for file reads + + TMPDIR Location for temporary files (except Windows) + TMP Location for temporary files (only Windows) + + AWS_ACCESS_KEY_ID Amazon S3 access key ID + AWS_SECRET_ACCESS_KEY Amazon S3 secret access key + AWS_SESSION_TOKEN Amazon S3 temporary session token + AWS_DEFAULT_REGION Amazon S3 default region + AWS_PROFILE Amazon credentials profile (alternative to specifying key and region) + AWS_SHARED_CREDENTIALS_FILE Location of the AWS CLI shared credentials file (default: ~/.aws/credentials) + RESTIC_AWS_ASSUME_ROLE_ARN Amazon IAM Role ARN to assume using discovered credentials + RESTIC_AWS_ASSUME_ROLE_SESSION_NAME Session Name to use with the role assumption + RESTIC_AWS_ASSUME_ROLE_EXTERNAL_ID External ID to use with the role assumption + RESTIC_AWS_ASSUME_ROLE_POLICY Inline Amazion IAM session policy + RESTIC_AWS_ASSUME_ROLE_REGION Region to use for IAM calls for the role assumption (default: us-east-1) + RESTIC_AWS_ASSUME_ROLE_STS_ENDPOINT URL to the STS endpoint (default is determined based on RESTIC_AWS_ASSUME_ROLE_REGION). You generally do not need to set this, advanced use only. + + AZURE_ACCOUNT_NAME Account name for Azure + AZURE_ACCOUNT_KEY Account key for Azure + AZURE_ACCOUNT_SAS Shared access signatures (SAS) for Azure + AZURE_ENDPOINT_SUFFIX Endpoint suffix for Azure Storage (default: core.windows.net) + AZURE_FORCE_CLI_CREDENTIAL Force the use of Azure CLI credentials for authentication + + B2_ACCOUNT_ID Account ID or applicationKeyId for Backblaze B2 + B2_ACCOUNT_KEY Account Key or applicationKey for Backblaze B2 + + GOOGLE_PROJECT_ID Project ID for Google Cloud Storage + GOOGLE_APPLICATION_CREDENTIALS Application Credentials for Google Cloud Storage (e.g. $HOME/.config/gs-secret-restic-key.json) + + OS_AUTH_URL Auth URL for keystone authentication + OS_REGION_NAME Region name for keystone authentication + OS_USERNAME Username for keystone authentication + OS_USER_ID User ID for keystone v3 authentication + OS_PASSWORD Password for keystone authentication + OS_TENANT_ID Tenant ID for keystone v2 authentication + OS_TENANT_NAME Tenant name for keystone v2 authentication + + OS_USER_DOMAIN_NAME User domain name for keystone authentication + OS_USER_DOMAIN_ID User domain ID for keystone v3 authentication + OS_PROJECT_NAME Project name for keystone authentication + OS_PROJECT_DOMAIN_NAME Project domain name for keystone authentication + OS_PROJECT_DOMAIN_ID Project domain ID for keystone v3 authentication + OS_TRUST_ID Trust ID for keystone v3 authentication + + OS_APPLICATION_CREDENTIAL_ID Application Credential ID (keystone v3) + OS_APPLICATION_CREDENTIAL_NAME Application Credential Name (keystone v3) + OS_APPLICATION_CREDENTIAL_SECRET Application Credential Secret (keystone v3) + + OS_STORAGE_URL Storage URL for token authentication + OS_AUTH_TOKEN Auth token for token authentication + + RCLONE_BWLIMIT rclone bandwidth limit + + RESTIC_REST_USERNAME Restic REST Server username + RESTIC_REST_PASSWORD Restic REST Server password + + ST_AUTH Auth URL for keystone v1 authentication + ST_USER Username for keystone v1 authentication + ST_KEY Password for keystone v1 authentication + +See :ref:`caching` for the rules concerning cache locations when +``RESTIC_CACHE_DIR`` is not set. + +The external programs that restic may execute include ``rclone`` (for rclone +backends) and ``ssh`` (for the SFTP backend). These may respond to further +environment variables and configuration files; see their respective manuals. Check if a repository is already initialized ******************************************** From 4bc6bb7e2731154a6b52a3285602e50e6ec3251b Mon Sep 17 00:00:00 2001 From: Michael Eischer Date: Sat, 31 Jan 2026 19:07:06 +0100 Subject: [PATCH 3/3] slightly reduce redundant wording --- doc/075_scripting.rst | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/doc/075_scripting.rst b/doc/075_scripting.rst index 299ea05ef..a24e597dd 100644 --- a/doc/075_scripting.rst +++ b/doc/075_scripting.rst @@ -14,8 +14,8 @@ Scripting ######################### -This section provides an overview of available environment variables and how -certain tasks may be accomplished when you use restic via scripts. +This section covers environment variables and how certain tasks may be accomplished +when you use restic via scripts. .. _environment-variables: @@ -23,7 +23,7 @@ Environment Variables ********************* In addition to command-line options, restic supports passing various options in -environment variables. The following lists these environment variables: +environment variables, which are listed below. .. code-block:: console