restic

Documentation

Overview

Package restic serves a remote suitable for use with restic

Index

• Variables
• func WithRemote(next http.Handler) http.Handler
• type Addr
  • func (a Addr) Network() string
  • func (a Addr) String() string
• type Options
• type StdioConn
  • func (s *StdioConn) Close() error
  • func (s *StdioConn) LocalAddr() net.Addr
  • func (s *StdioConn) Read(p []byte) (int, error)
  • func (s *StdioConn) RemoteAddr() net.Addr
  • func (s *StdioConn) SetDeadline(t time.Time) error
  • func (s *StdioConn) SetReadDeadline(t time.Time) error
  • func (s *StdioConn) SetWriteDeadline(t time.Time) error
  • func (s *StdioConn) Write(p []byte) (int, error)

Variables

var Command = &cobra.Command{
	Use:   "restic remote:path",
	Short: `Serve the remote for restic's REST API.`,
	Long: `Run a basic web server to serve a remote over restic's REST backend
API over HTTP.  This allows restic to use rclone as a data storage
mechanism for cloud providers that restic does not support directly.

[Restic](https://restic.net/) is a command-line program for doing
backups.

The server will log errors.  Use -v to see access logs.

` + "`--bwlimit`" + ` will be respected for file transfers.
Use ` + "`--stats`" + ` to control the stats printing.

### Setting up rclone for use by restic ###

First [set up a remote for your chosen cloud provider](/docs/#configure).

Once you have set up the remote, check it is working with, for example
"rclone lsd remote:".  You may have called the remote something other
than "remote:" - just substitute whatever you called it in the
following instructions.

Now start the rclone restic server

    rclone serve restic -v remote:backup

Where you can replace "backup" in the above by whatever path in the
remote you wish to use.

By default this will serve on "localhost:8080" you can change this
with use of the ` + "`--addr`" + ` flag.

You might wish to start this server on boot.

Adding ` + "`--cache-objects=false`" + ` will cause rclone to stop caching objects
returned from the List call. Caching is normally desirable as it speeds
up downloading objects, saves transactions and uses very little memory.

### Setting up restic to use rclone ###

Now you can [follow the restic
instructions](http://restic.readthedocs.io/en/latest/030_preparing_a_new_repo.html#rest-server)
on setting up restic.

Note that you will need restic 0.8.2 or later to interoperate with
rclone.

For the example above you will want to use "http://localhost:8080/" as
the URL for the REST server.

For example:

    $ export RESTIC_REPOSITORY=rest:http://localhost:8080/
    $ export RESTIC_PASSWORD=yourpassword
    $ restic init
    created restic backend 8b1a4b56ae at rest:http://localhost:8080/

    Please note that knowledge of your password is required to access
    the repository. Losing your password means that your data is
    irrecoverably lost.
    $ restic backup /path/to/files/to/backup
    scan [/path/to/files/to/backup]
    scanned 189 directories, 312 files in 0:00
    [0:00] 100.00%  38.128 MiB / 38.128 MiB  501 / 501 items  0 errors  ETA 0:00
    duration: 0:00
    snapshot 45c8fdd8 saved

#### Multiple repositories ####

Note that you can use the endpoint to host multiple repositories.  Do
this by adding a directory name or path after the URL.  Note that
these **must** end with /.  Eg

    $ export RESTIC_REPOSITORY=rest:http://localhost:8080/user1repo/
    # backup user1 stuff
    $ export RESTIC_REPOSITORY=rest:http://localhost:8080/user2repo/
    # backup user2 stuff

#### Private repositories ####

The` + "`--private-repos`" + ` flag can be used to limit users to repositories starting
with a path of ` + "`/<username>/`" + `.
` + libhttp.Help(flagPrefix) + libhttp.AuthHelp(flagPrefix),
	Annotations: map[string]string{
		"versionIntroduced": "v1.40",
	},
	Run: func(command *cobra.Command, args []string) {
		ctx := context.Background()
		cmd.CheckArgs(1, 1, command, args)
		f := cmd.NewFsSrc(args)
		cmd.Run(false, true, command, func() error {
			s, err := newServer(ctx, f, &Opt)
			if err != nil {
				return err
			}
			if s.opt.Stdio {
				if terminal.IsTerminal(int(os.Stdout.Fd())) {
					return errors.New("refusing to run HTTP2 server directly on a terminal, please let restic start rclone")
				}

				conn := &StdioConn{
					stdin:  os.Stdin,
					stdout: os.Stdout,
				}

				httpSrv := &http2.Server{}
				opts := &http2.ServeConnOpts{
					Handler: s.Server.Router(),
				}
				httpSrv.ServeConn(conn, opts)
				return nil
			}
			fs.Logf(s.f, "Serving restic REST API on %s", s.URLs())

			defer systemd.Notify()()
			s.Wait()

			return nil
		})
	},
}

Command definition for cobra

var ContextRemoteKey = &contextRemoteType{}

ContextRemoteKey is a simple context key for storing the username of the request

var DefaultOpt = Options{
	Auth: libhttp.DefaultAuthCfg(),
	HTTP: libhttp.DefaultCfg(),
}

DefaultOpt is the default values used for Options

var Opt = DefaultOpt

Opt is options set by command line flags

Functions

func WithRemote

func WithRemote(next http.Handler) http.Handler

WithRemote makes a remote from a URL path. This implements the backend layout required by restic.

Types

type Addr

type Addr struct{}

Addr implements net.Addr for stdin/stdout.

func (Addr) Network

func (a Addr) Network() string

Network returns the network type as a string.

func (Addr) String

func (a Addr) String() string

type Options

type Options struct {
	Auth         libhttp.AuthConfig
	HTTP         libhttp.Config
	Stdio        bool
	AppendOnly   bool
	PrivateRepos bool
	CacheObjects bool
}

Options required for http server

type StdioConn

type StdioConn struct {
	// contains filtered or unexported fields
}

StdioConn implements a net.Conn via stdin/stdout.

func (*StdioConn) Close

func (s *StdioConn) Close() error

Close closes both streams.

func (*StdioConn) LocalAddr

func (s *StdioConn) LocalAddr() net.Addr

LocalAddr returns nil.

func (*StdioConn) Read

func (s *StdioConn) Read(p []byte) (int, error)

func (*StdioConn) RemoteAddr

func (s *StdioConn) RemoteAddr() net.Addr

RemoteAddr returns nil.

func (*StdioConn) SetDeadline

func (s *StdioConn) SetDeadline(t time.Time) error

SetDeadline sets the read/write deadline.

func (*StdioConn) SetReadDeadline

func (s *StdioConn) SetReadDeadline(t time.Time) error

SetReadDeadline sets the read/write deadline.

func (*StdioConn) SetWriteDeadline

func (s *StdioConn) SetWriteDeadline(t time.Time) error

SetWriteDeadline sets the read/write deadline.

func (*StdioConn) Write

func (s *StdioConn) Write(p []byte) (int, error)