github.com/xhghs/rclone@v1.51.1-0.20200430155106-e186a28cced8/docs/content/commands/rclone_serve_restic.md

github.com/xhghs/rclone@v1.51.1-0.20200430155106-e186a28cced8/docs/content/commands/rclone_serve_restic.md (about)

1 ---
2 date: 2020-02-01T10:26:53Z
3 title: "rclone serve restic"
4 slug: rclone_serve_restic
5 url: /commands/rclone_serve_restic/
6 ---
7 ## rclone serve restic
8
9 Serve the remote for restic's REST API.
10
11 ### Synopsis
12
13 rclone serve restic implements restic's REST backend API
14 over HTTP. This allows restic to use rclone as a data storage
15 mechanism for cloud providers that restic does not support directly.
16
17 [Restic](https://restic.net/) is a command line program for doing
18 backups.
19
20 The server will log errors. Use -v to see access logs.
21
22 --bwlimit will be respected for file transfers. Use --stats to
23 control the stats printing.
24
25 ### Setting up rclone for use by restic ###
26
27 First [set up a remote for your chosen cloud provider](/docs/#configure).
28
29 Once you have set up the remote, check it is working with, for example
30 "rclone lsd remote:". You may have called the remote something other
31 than "remote:" - just substitute whatever you called it in the
32 following instructions.
33
34 Now start the rclone restic server
35
36 rclone serve restic -v remote:backup
37
38 Where you can replace "backup" in the above by whatever path in the
39 remote you wish to use.
40
41 By default this will serve on "localhost:8080" you can change this
42 with use of the "--addr" flag.
43
44 You might wish to start this server on boot.
45
46 ### Setting up restic to use rclone ###
47
48 Now you can [follow the restic
49 instructions](http://restic.readthedocs.io/en/latest/030_preparing_a_new_repo.html#rest-server)
50 on setting up restic.
51
52 Note that you will need restic 0.8.2 or later to interoperate with
53 rclone.
54
55 For the example above you will want to use "http://localhost:8080/" as
56 the URL for the REST server.
57
58 For example:
59
60 $ export RESTIC_REPOSITORY=rest:http://localhost:8080/
61 $ export RESTIC_PASSWORD=yourpassword
62 $ restic init
63 created restic backend 8b1a4b56ae at rest:http://localhost:8080/
64
65 Please note that knowledge of your password is required to access
66 the repository. Losing your password means that your data is
67 irrecoverably lost.
68 $ restic backup /path/to/files/to/backup
69 scan [/path/to/files/to/backup]
70 scanned 189 directories, 312 files in 0:00
71 [0:00] 100.00% 38.128 MiB / 38.128 MiB 501 / 501 items 0 errors ETA 0:00
72 duration: 0:00
73 snapshot 45c8fdd8 saved
74
75 #### Multiple repositories ####
76
77 Note that you can use the endpoint to host multiple repositories. Do
78 this by adding a directory name or path after the URL. Note that
79 these **must** end with /. Eg
80
81 $ export RESTIC_REPOSITORY=rest:http://localhost:8080/user1repo/
82 # backup user1 stuff
83 $ export RESTIC_REPOSITORY=rest:http://localhost:8080/user2repo/
84 # backup user2 stuff
85
86 #### Private repositories ####
87
88 The "--private-repos" flag can be used to limit users to repositories starting
89 with a path of "/<username>/".
90
91 ### Server options
92
93 Use --addr to specify which IP address and port the server should
94 listen on, eg --addr 1.2.3.4:8000 or --addr :8080 to listen to all
95 IPs. By default it only listens on localhost. You can use port
96 :0 to let the OS choose an available port.
97
98 If you set --addr to listen on a public or LAN accessible IP address
99 then using Authentication is advised - see the next section for info.
100
101 --server-read-timeout and --server-write-timeout can be used to
102 control the timeouts on the server. Note that this is the total time
103 for a transfer.
104
105 --max-header-bytes controls the maximum number of bytes the server will
106 accept in the HTTP header.
107
108 --baseurl controls the URL prefix that rclone serves from. By default
109 rclone will serve from the root. If you used --baseurl "/rclone" then
110 rclone would serve from a URL starting with "/rclone/". This is
111 useful if you wish to proxy rclone serve. Rclone automatically
112 inserts leading and trailing "/" on --baseurl, so --baseurl "rclone",
113 --baseurl "/rclone" and --baseurl "/rclone/" are all treated
114 identically.
115
116 #### Authentication
117
118 By default this will serve files without needing a login.
119
120 You can either use an htpasswd file which can take lots of users, or
121 set a single username and password with the --user and --pass flags.
122
123 Use --htpasswd /path/to/htpasswd to provide an htpasswd file. This is
124 in standard apache format and supports MD5, SHA1 and BCrypt for basic
125 authentication. Bcrypt is recommended.
126
127 To create an htpasswd file:
128
129 touch htpasswd
130 htpasswd -B htpasswd user
131 htpasswd -B htpasswd anotherUser
132
133 The password file can be updated while rclone is running.
134
135 Use --realm to set the authentication realm.
136
137 #### SSL/TLS
138
139 By default this will serve over http. If you want you can serve over
140 https. You will need to supply the --cert and --key flags. If you
141 wish to do client side certificate validation then you will need to
142 supply --client-ca also.
143
144 --cert should be a either a PEM encoded certificate or a concatenation
145 of that with the CA certificate. --key should be the PEM encoded
146 private key and --client-ca should be the PEM encoded client
147 certificate authority certificate.
148
149
150 ```
151 rclone serve restic remote:path [flags]
152 ```
153
154 ### Options
155
156 ```
157 --addr string IPaddress:Port or :Port to bind server to. (default "localhost:8080")
158 --append-only disallow deletion of repository data
159 --baseurl string Prefix for URLs - leave blank for root.
160 --cert string SSL PEM key (concatenation of certificate and CA certificate)
161 --client-ca string Client certificate authority to verify clients with
162 -h, --help help for restic
163 --htpasswd string htpasswd file - if not provided no authentication is done
164 --key string SSL PEM Private key
165 --max-header-bytes int Maximum size of request header (default 4096)
166 --pass string Password for authentication.
167 --private-repos users can only access their private repo
168 --realm string realm for authentication (default "rclone")
169 --server-read-timeout duration Timeout for server reading data (default 1h0m0s)
170 --server-write-timeout duration Timeout for server writing data (default 1h0m0s)
171 --stdio run an HTTP2 server on stdin/stdout
172 --user string User name for authentication.
173 ```
174
175 See the [global flags page](/flags/) for global options not listed here.
176
177 ### SEE ALSO
178
179 * [rclone serve](/commands/rclone_serve/) - Serve a remote over a protocol.
180