github.com/mckael/restic@v0.8.3/doc/030_preparing_a_new_repo.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 Preparing a new repository 15 ########################## 16 17 The place where your backups will be saved at is called a "repository". 18 This chapter explains how to create ("init") such a repository. 19 20 Local 21 ***** 22 23 In order to create a repository at ``/tmp/backup``, run the following 24 command and enter the same password twice: 25 26 .. code-block:: console 27 28 $ restic init --repo /tmp/backup 29 enter password for new backend: 30 enter password again: 31 created restic backend 085b3c76b9 at /tmp/backup 32 Please note that knowledge of your password is required to access the repository. 33 Losing your password means that your data is irrecoverably lost. 34 35 .. warning:: 36 37 Remembering your password is important! If you lose it, you won't be 38 able to access data stored in the repository. 39 40 For automated backups, restic accepts the repository location in the 41 environment variable ``RESTIC_REPOSITORY``. The password can be read 42 from a file (via the option ``--password-file`` or the environment variable 43 ``RESTIC_PASSWORD_FILE``) or the environment variable ``RESTIC_PASSWORD``. 44 45 SFTP 46 **** 47 48 In order to backup data via SFTP, you must first set up a server with 49 SSH and let it know your public key. Passwordless login is really 50 important since restic fails to connect to the repository if the server 51 prompts for credentials. 52 53 Once the server is configured, the setup of the SFTP repository can 54 simply be achieved by changing the URL scheme in the ``init`` command: 55 56 .. code-block:: console 57 58 $ restic -r sftp:user@host:/tmp/backup init 59 enter password for new backend: 60 enter password again: 61 created restic backend f1c6108821 at sftp:user@host:/tmp/backup 62 Please note that knowledge of your password is required to access the repository. 63 Losing your password means that your data is irrecoverably lost. 64 65 You can also specify a relative (read: no slash (``/``) character at the 66 beginning) directory, in this case the dir is relative to the remote 67 user's home directory. 68 69 .. note:: Please be aware that sftp servers do not expand the tilde character 70 (``~``) normally used as an alias for a user's home directory. If you 71 want to specify a path relative to the user's home directory, pass a 72 relative path to the sftp backend. 73 74 The backend config string does not allow specifying a port. If you need 75 to contact an sftp server on a different port, you can create an entry 76 in the ``ssh`` file, usually located in your user's home directory at 77 ``~/.ssh/config`` or in ``/etc/ssh/ssh_config``: 78 79 :: 80 81 Host foo 82 User bar 83 Port 2222 84 85 Then use the specified host name ``foo`` normally (you don't need to 86 specify the user name in this case): 87 88 :: 89 90 $ restic -r sftp:foo:/tmp/backup init 91 92 You can also add an entry with a special host name which does not exist, 93 just for use with restic, and use the ``Hostname`` option to set the 94 real host name: 95 96 :: 97 98 Host restic-backup-host 99 Hostname foo 100 User bar 101 Port 2222 102 103 Then use it in the backend specification: 104 105 :: 106 107 $ restic -r sftp:restic-backup-host:/tmp/backup init 108 109 Last, if you'd like to use an entirely different program to create the 110 SFTP connection, you can specify the command to be run with the option 111 ``-o sftp.command="foobar"``. 112 113 114 REST Server 115 *********** 116 117 In order to backup data to the remote server via HTTP or HTTPS protocol, 118 you must first set up a remote `REST 119 server <https://github.com/restic/rest-server>`__ instance. Once the 120 server is configured, accessing it is achieved by changing the URL 121 scheme like this: 122 123 .. code-block:: console 124 125 $ restic -r rest:http://host:8000/ 126 127 Depending on your REST server setup, you can use HTTPS protocol, 128 password protection, or multiple repositories. Or any combination of 129 those features, as you see fit. TCP/IP port is also configurable. Here 130 are some more examples: 131 132 .. code-block:: console 133 134 $ restic -r rest:https://host:8000/ 135 $ restic -r rest:https://user:pass@host:8000/ 136 $ restic -r rest:https://user:pass@host:8000/my_backup_repo/ 137 138 If you use TLS, restic will use the system's CA certificates to verify the 139 server certificate. When the verification fails, restic refuses to proceed and 140 exits with an error. If you have your own self-signed certificate, or a custom 141 CA certificate should be used for verification, you can pass restic the 142 certificate filename via the `--cacert` option. 143 144 REST server uses exactly the same directory structure as local backend, 145 so you should be able to access it both locally and via HTTP, even 146 simultaneously. 147 148 Amazon S3 149 ********* 150 151 Restic can backup data to any Amazon S3 bucket. However, in this case, 152 changing the URL scheme is not enough since Amazon uses special security 153 credentials to sign HTTP requests. By consequence, you must first setup 154 the following environment variables with the credentials you obtained 155 while creating the bucket. 156 157 .. code-block:: console 158 159 $ export AWS_ACCESS_KEY_ID=<MY_ACCESS_KEY> 160 $ export AWS_SECRET_ACCESS_KEY=<MY_SECRET_ACCESS_KEY> 161 162 You can then easily initialize a repository that uses your Amazon S3 as 163 a backend, if the bucket does not exist yet it will be created in the 164 default location: 165 166 .. code-block:: console 167 168 $ restic -r s3:s3.amazonaws.com/bucket_name init 169 enter password for new backend: 170 enter password again: 171 created restic backend eefee03bbd at s3:s3.amazonaws.com/bucket_name 172 Please note that knowledge of your password is required to access the repository. 173 Losing your password means that your data is irrecoverably lost. 174 175 It is not possible at the moment to have restic create a new bucket in a 176 different location, so you need to create it using a different program. 177 Afterwards, the S3 server (``s3.amazonaws.com``) will redirect restic to 178 the correct endpoint. 179 180 Until version 0.8.0, restic used a default prefix of ``restic``, so the files 181 in the bucket were placed in a directory named ``restic``. If you want to 182 access a repository created with an older version of restic, specify the path 183 after the bucket name like this: 184 185 .. code-block:: console 186 187 $ restic -r s3:s3.amazonaws.com/bucket_name/restic [...] 188 189 For an S3-compatible server that is not Amazon (like Minio, see below), 190 or is only available via HTTP, you can specify the URL to the server 191 like this: ``s3:http://server:port/bucket_name``. 192 193 Minio Server 194 ************ 195 196 `Minio <https://www.minio.io>`__ is an Open Source Object Storage, 197 written in Go and compatible with AWS S3 API. 198 199 - Download and Install `Minio 200 Server <https://minio.io/downloads/#minio-server>`__. 201 - You can also refer to https://docs.minio.io for step by step guidance 202 on installation and getting started on Minio Client and Minio Server. 203 204 You must first setup the following environment variables with the 205 credentials of your running Minio Server. 206 207 .. code-block:: console 208 209 $ export AWS_ACCESS_KEY_ID=<YOUR-MINIO-ACCESS-KEY-ID> 210 $ export AWS_SECRET_ACCESS_KEY= <YOUR-MINIO-SECRET-ACCESS-KEY> 211 212 Now you can easily initialize restic to use Minio server as backend with 213 this command. 214 215 .. code-block:: console 216 217 $ ./restic -r s3:http://localhost:9000/restic init 218 enter password for new backend: 219 enter password again: 220 created restic backend 6ad29560f5 at s3:http://localhost:9000/restic1 221 Please note that knowledge of your password is required to access 222 the repository. Losing your password means that your data is irrecoverably lost. 223 224 OpenStack Swift 225 *************** 226 227 Restic can backup data to an OpenStack Swift container. Because Swift supports 228 various authentication methods, credentials are passed through environment 229 variables. In order to help integration with existing OpenStack installations, 230 the naming convention of those variables follows official python swift client: 231 232 .. code-block:: console 233 234 # For keystone v1 authentication 235 $ export ST_AUTH=<MY_AUTH_URL> 236 $ export ST_USER=<MY_USER_NAME> 237 $ export ST_KEY=<MY_USER_PASSWORD> 238 239 # For keystone v2 authentication (some variables are optional) 240 $ export OS_AUTH_URL=<MY_AUTH_URL> 241 $ export OS_REGION_NAME=<MY_REGION_NAME> 242 $ export OS_USERNAME=<MY_USERNAME> 243 $ export OS_PASSWORD=<MY_PASSWORD> 244 $ export OS_TENANT_ID=<MY_TENANT_ID> 245 $ export OS_TENANT_NAME=<MY_TENANT_NAME> 246 247 # For keystone v3 authentication (some variables are optional) 248 $ export OS_AUTH_URL=<MY_AUTH_URL> 249 $ export OS_REGION_NAME=<MY_REGION_NAME> 250 $ export OS_USERNAME=<MY_USERNAME> 251 $ export OS_PASSWORD=<MY_PASSWORD> 252 $ export OS_USER_DOMAIN_NAME=<MY_DOMAIN_NAME> 253 $ export OS_PROJECT_NAME=<MY_PROJECT_NAME> 254 $ export OS_PROJECT_DOMAIN_NAME=<MY_PROJECT_DOMAIN_NAME> 255 256 # For authentication based on tokens 257 $ export OS_STORAGE_URL=<MY_STORAGE_URL> 258 $ export OS_AUTH_TOKEN=<MY_AUTH_TOKEN> 259 260 261 Restic should be compatible with `OpenStack RC file 262 <https://docs.openstack.org/user-guide/common/cli-set-environment-variables-using-openstack-rc.html>`__ 263 in most cases. 264 265 Once environment variables are set up, a new repository can be created. The 266 name of swift container and optional path can be specified. If 267 the container does not exist, it will be created automatically: 268 269 .. code-block:: console 270 271 $ restic -r swift:container_name:/path init # path is optional 272 enter password for new backend: 273 enter password again: 274 created restic backend eefee03bbd at swift:container_name:/path 275 Please note that knowledge of your password is required to access the repository. 276 Losing your password means that your data is irrecoverably lost. 277 278 The policy of new container created by restic can be changed using environment variable: 279 280 .. code-block:: console 281 282 $ export SWIFT_DEFAULT_CONTAINER_POLICY=<MY_CONTAINER_POLICY> 283 284 285 Backblaze B2 286 ************ 287 288 Restic can backup data to any Backblaze B2 bucket. You need to first setup the 289 following environment variables with the credentials you obtained when signed 290 into your B2 account: 291 292 .. code-block:: console 293 294 $ export B2_ACCOUNT_ID=<MY_ACCOUNT_ID> 295 $ export B2_ACCOUNT_KEY=<MY_SECRET_ACCOUNT_KEY> 296 297 You can then easily initialize a repository stored at Backblaze B2. If the 298 bucket does not exist yet, it will be created: 299 300 .. code-block:: console 301 302 $ restic -r b2:bucketname:path/to/repo init 303 enter password for new backend: 304 enter password again: 305 created restic backend eefee03bbd at b2:bucketname:path/to/repo 306 Please note that knowledge of your password is required to access the repository. 307 Losing your password means that your data is irrecoverably lost. 308 309 The number of concurrent connections to the B2 service can be set with the `-o 310 b2.connections=10`. By default, at most five parallel connections are 311 established. 312 313 Microsoft Azure Blob Storage 314 **************************** 315 316 You can also store backups on Microsoft Azure Blob Storage. Export the Azure 317 account name and key as follows: 318 319 .. code-block:: console 320 321 $ export AZURE_ACCOUNT_NAME=<ACCOUNT_NAME> 322 $ export AZURE_ACCOUNT_KEY=<SECRET_KEY> 323 324 Afterwards you can initialize a repository in a container called `foo` in the 325 root path like this: 326 327 .. code-block:: console 328 329 $ restic -r azure:foo:/ init 330 enter password for new backend: 331 enter password again: 332 333 created restic backend a934bac191 at azure:foo:/ 334 [...] 335 336 The number of concurrent connections to the Azure Blob Storage service can be set with the 337 `-o azure.connections=10`. By default, at most five parallel connections are 338 established. 339 340 Google Cloud Storage 341 ******************** 342 343 Restic supports Google Cloud Storage as a backend. 344 345 Restic connects to Google Cloud Storage via a `service account`_. 346 347 For normal restic operation, the service account must have the 348 ``storage.objects.{create,delete,get,list}`` permissions for the bucket. These 349 are included in the "Storage Object Admin" role. 350 ``restic init`` can create the repository bucket. Doing so requires the 351 ``storage.buckets.create`` permission ("Storage Admin" role). If the bucket 352 already exists, that permission is unnecessary. 353 354 To use the Google Cloud Storage backend, first `create a service account key`_ 355 and download the JSON credentials file. 356 Second, find the Google Project ID that you can see in the Google Cloud 357 Platform console at the "Storage/Settings" menu. Export the path to the JSON 358 key file and the project ID as follows: 359 360 .. code-block:: console 361 362 $ export GOOGLE_PROJECT_ID=123123123123 363 $ export GOOGLE_APPLICATION_CREDENTIALS=$HOME/.config/gs-secret-restic-key.json 364 365 Then you can use the ``gs:`` backend type to create a new repository in the 366 bucket `foo` at the root path: 367 368 .. code-block:: console 369 370 $ restic -r gs:foo:/ init 371 enter password for new backend: 372 enter password again: 373 374 created restic backend bde47d6254 at gs:foo2/ 375 [...] 376 377 The number of concurrent connections to the GCS service can be set with the 378 `-o gs.connections=10`. By default, at most five parallel connections are 379 established. 380 381 .. _service account: https://cloud.google.com/storage/docs/authentication#service_accounts 382 .. _create a service account key: https://cloud.google.com/storage/docs/authentication#generating-a-private-key 383 384 Password prompt on Windows 385 ************************** 386 387 At the moment, restic only supports the default Windows console 388 interaction. If you use emulation environments like 389 `MSYS2 <https://msys2.github.io/>`__ or 390 `Cygwin <https://www.cygwin.com/>`__, which use terminals like 391 ``Mintty`` or ``rxvt``, you may get a password error: 392 393 You can workaround this by using a special tool called ``winpty`` (look 394 `here <https://sourceforge.net/p/msys2/wiki/Porting/>`__ and 395 `here <https://github.com/rprichard/winpty>`__ for detail information). 396 On MSYS2, you can install ``winpty`` as follows: 397 398 .. code-block:: console 399 400 $ pacman -S winpty 401 $ winpty restic -r /tmp/backup init 402