gopkg.in/dotcloud/docker.v1@v1.13.1/daemon/graphdriver/driver.go (about)

     1  package graphdriver
     2  
     3  import (
     4  	"errors"
     5  	"fmt"
     6  	"io"
     7  	"os"
     8  	"path/filepath"
     9  	"strings"
    10  
    11  	"github.com/Sirupsen/logrus"
    12  	"github.com/vbatts/tar-split/tar/storage"
    13  
    14  	"github.com/docker/docker/pkg/archive"
    15  	"github.com/docker/docker/pkg/idtools"
    16  	"github.com/docker/docker/pkg/plugingetter"
    17  )
    18  
    19  // FsMagic unsigned id of the filesystem in use.
    20  type FsMagic uint32
    21  
    22  const (
    23  	// FsMagicUnsupported is a predefined constant value other than a valid filesystem id.
    24  	FsMagicUnsupported = FsMagic(0x00000000)
    25  )
    26  
    27  var (
    28  	// All registered drivers
    29  	drivers map[string]InitFunc
    30  
    31  	// ErrNotSupported returned when driver is not supported.
    32  	ErrNotSupported = errors.New("driver not supported")
    33  	// ErrPrerequisites retuned when driver does not meet prerequisites.
    34  	ErrPrerequisites = errors.New("prerequisites for driver not satisfied (wrong filesystem?)")
    35  	// ErrIncompatibleFS returned when file system is not supported.
    36  	ErrIncompatibleFS = fmt.Errorf("backing file system is unsupported for this graph driver")
    37  )
    38  
    39  //CreateOpts contains optional arguments for Create() and CreateReadWrite()
    40  // methods.
    41  type CreateOpts struct {
    42  	MountLabel string
    43  	StorageOpt map[string]string
    44  }
    45  
    46  // InitFunc initializes the storage driver.
    47  type InitFunc func(root string, options []string, uidMaps, gidMaps []idtools.IDMap) (Driver, error)
    48  
    49  // ProtoDriver defines the basic capabilities of a driver.
    50  // This interface exists solely to be a minimum set of methods
    51  // for client code which choose not to implement the entire Driver
    52  // interface and use the NaiveDiffDriver wrapper constructor.
    53  //
    54  // Use of ProtoDriver directly by client code is not recommended.
    55  type ProtoDriver interface {
    56  	// String returns a string representation of this driver.
    57  	String() string
    58  	// CreateReadWrite creates a new, empty filesystem layer that is ready
    59  	// to be used as the storage for a container. Additional options can
    60  	// be passed in opts. parent may be "" and opts may be nil.
    61  	CreateReadWrite(id, parent string, opts *CreateOpts) error
    62  	// Create creates a new, empty, filesystem layer with the
    63  	// specified id and parent and options passed in opts. Parent
    64  	// may be "" and opts may be nil.
    65  	Create(id, parent string, opts *CreateOpts) error
    66  	// Remove attempts to remove the filesystem layer with this id.
    67  	Remove(id string) error
    68  	// Get returns the mountpoint for the layered filesystem referred
    69  	// to by this id. You can optionally specify a mountLabel or "".
    70  	// Returns the absolute path to the mounted layered filesystem.
    71  	Get(id, mountLabel string) (dir string, err error)
    72  	// Put releases the system resources for the specified id,
    73  	// e.g, unmounting layered filesystem.
    74  	Put(id string) error
    75  	// Exists returns whether a filesystem layer with the specified
    76  	// ID exists on this driver.
    77  	Exists(id string) bool
    78  	// Status returns a set of key-value pairs which give low
    79  	// level diagnostic status about this driver.
    80  	Status() [][2]string
    81  	// Returns a set of key-value pairs which give low level information
    82  	// about the image/container driver is managing.
    83  	GetMetadata(id string) (map[string]string, error)
    84  	// Cleanup performs necessary tasks to release resources
    85  	// held by the driver, e.g., unmounting all layered filesystems
    86  	// known to this driver.
    87  	Cleanup() error
    88  }
    89  
    90  // DiffDriver is the interface to use to implement graph diffs
    91  type DiffDriver interface {
    92  	// Diff produces an archive of the changes between the specified
    93  	// layer and its parent layer which may be "".
    94  	Diff(id, parent string) (io.ReadCloser, error)
    95  	// Changes produces a list of changes between the specified layer
    96  	// and its parent layer. If parent is "", then all changes will be ADD changes.
    97  	Changes(id, parent string) ([]archive.Change, error)
    98  	// ApplyDiff extracts the changeset from the given diff into the
    99  	// layer with the specified id and parent, returning the size of the
   100  	// new layer in bytes.
   101  	// The archive.Reader must be an uncompressed stream.
   102  	ApplyDiff(id, parent string, diff io.Reader) (size int64, err error)
   103  	// DiffSize calculates the changes between the specified id
   104  	// and its parent and returns the size in bytes of the changes
   105  	// relative to its base filesystem directory.
   106  	DiffSize(id, parent string) (size int64, err error)
   107  }
   108  
   109  // Driver is the interface for layered/snapshot file system drivers.
   110  type Driver interface {
   111  	ProtoDriver
   112  	DiffDriver
   113  }
   114  
   115  // DiffGetterDriver is the interface for layered file system drivers that
   116  // provide a specialized function for getting file contents for tar-split.
   117  type DiffGetterDriver interface {
   118  	Driver
   119  	// DiffGetter returns an interface to efficiently retrieve the contents
   120  	// of files in a layer.
   121  	DiffGetter(id string) (FileGetCloser, error)
   122  }
   123  
   124  // FileGetCloser extends the storage.FileGetter interface with a Close method
   125  // for cleaning up.
   126  type FileGetCloser interface {
   127  	storage.FileGetter
   128  	// Close cleans up any resources associated with the FileGetCloser.
   129  	Close() error
   130  }
   131  
   132  // Checker makes checks on specified filesystems.
   133  type Checker interface {
   134  	// IsMounted returns true if the provided path is mounted for the specific checker
   135  	IsMounted(path string) bool
   136  }
   137  
   138  func init() {
   139  	drivers = make(map[string]InitFunc)
   140  }
   141  
   142  // Register registers an InitFunc for the driver.
   143  func Register(name string, initFunc InitFunc) error {
   144  	if _, exists := drivers[name]; exists {
   145  		return fmt.Errorf("Name already registered %s", name)
   146  	}
   147  	drivers[name] = initFunc
   148  
   149  	return nil
   150  }
   151  
   152  // GetDriver initializes and returns the registered driver
   153  func GetDriver(name string, pg plugingetter.PluginGetter, config Options) (Driver, error) {
   154  	if initFunc, exists := drivers[name]; exists {
   155  		return initFunc(filepath.Join(config.Root, name), config.DriverOptions, config.UIDMaps, config.GIDMaps)
   156  	}
   157  
   158  	pluginDriver, err := lookupPlugin(name, pg, config)
   159  	if err == nil {
   160  		return pluginDriver, nil
   161  	}
   162  	logrus.WithError(err).WithField("driver", name).WithField("home-dir", config.Root).Error("Failed to GetDriver graph")
   163  	return nil, ErrNotSupported
   164  }
   165  
   166  // getBuiltinDriver initializes and returns the registered driver, but does not try to load from plugins
   167  func getBuiltinDriver(name, home string, options []string, uidMaps, gidMaps []idtools.IDMap) (Driver, error) {
   168  	if initFunc, exists := drivers[name]; exists {
   169  		return initFunc(filepath.Join(home, name), options, uidMaps, gidMaps)
   170  	}
   171  	logrus.Errorf("Failed to built-in GetDriver graph %s %s", name, home)
   172  	return nil, ErrNotSupported
   173  }
   174  
   175  // Options is used to initialize a graphdriver
   176  type Options struct {
   177  	Root                string
   178  	DriverOptions       []string
   179  	UIDMaps             []idtools.IDMap
   180  	GIDMaps             []idtools.IDMap
   181  	ExperimentalEnabled bool
   182  }
   183  
   184  // New creates the driver and initializes it at the specified root.
   185  func New(name string, pg plugingetter.PluginGetter, config Options) (Driver, error) {
   186  	if name != "" {
   187  		logrus.Debugf("[graphdriver] trying provided driver: %s", name) // so the logs show specified driver
   188  		return GetDriver(name, pg, config)
   189  	}
   190  
   191  	// Guess for prior driver
   192  	driversMap := scanPriorDrivers(config.Root)
   193  	for _, name := range priority {
   194  		if name == "vfs" {
   195  			// don't use vfs even if there is state present.
   196  			continue
   197  		}
   198  		if _, prior := driversMap[name]; prior {
   199  			// of the state found from prior drivers, check in order of our priority
   200  			// which we would prefer
   201  			driver, err := getBuiltinDriver(name, config.Root, config.DriverOptions, config.UIDMaps, config.GIDMaps)
   202  			if err != nil {
   203  				// unlike below, we will return error here, because there is prior
   204  				// state, and now it is no longer supported/prereq/compatible, so
   205  				// something changed and needs attention. Otherwise the daemon's
   206  				// images would just "disappear".
   207  				logrus.Errorf("[graphdriver] prior storage driver %s failed: %s", name, err)
   208  				return nil, err
   209  			}
   210  
   211  			// abort starting when there are other prior configured drivers
   212  			// to ensure the user explicitly selects the driver to load
   213  			if len(driversMap)-1 > 0 {
   214  				var driversSlice []string
   215  				for name := range driversMap {
   216  					driversSlice = append(driversSlice, name)
   217  				}
   218  
   219  				return nil, fmt.Errorf("%s contains several valid graphdrivers: %s; Please cleanup or explicitly choose storage driver (-s <DRIVER>)", config.Root, strings.Join(driversSlice, ", "))
   220  			}
   221  
   222  			logrus.Infof("[graphdriver] using prior storage driver: %s", name)
   223  			return driver, nil
   224  		}
   225  	}
   226  
   227  	// Check for priority drivers first
   228  	for _, name := range priority {
   229  		driver, err := getBuiltinDriver(name, config.Root, config.DriverOptions, config.UIDMaps, config.GIDMaps)
   230  		if err != nil {
   231  			if isDriverNotSupported(err) {
   232  				continue
   233  			}
   234  			return nil, err
   235  		}
   236  		return driver, nil
   237  	}
   238  
   239  	// Check all registered drivers if no priority driver is found
   240  	for name, initFunc := range drivers {
   241  		driver, err := initFunc(filepath.Join(config.Root, name), config.DriverOptions, config.UIDMaps, config.GIDMaps)
   242  		if err != nil {
   243  			if isDriverNotSupported(err) {
   244  				continue
   245  			}
   246  			return nil, err
   247  		}
   248  		return driver, nil
   249  	}
   250  	return nil, fmt.Errorf("No supported storage backend found")
   251  }
   252  
   253  // isDriverNotSupported returns true if the error initializing
   254  // the graph driver is a non-supported error.
   255  func isDriverNotSupported(err error) bool {
   256  	return err == ErrNotSupported || err == ErrPrerequisites || err == ErrIncompatibleFS
   257  }
   258  
   259  // scanPriorDrivers returns an un-ordered scan of directories of prior storage drivers
   260  func scanPriorDrivers(root string) map[string]bool {
   261  	driversMap := make(map[string]bool)
   262  
   263  	for driver := range drivers {
   264  		p := filepath.Join(root, driver)
   265  		if _, err := os.Stat(p); err == nil && driver != "vfs" {
   266  			driversMap[driver] = true
   267  		}
   268  	}
   269  	return driversMap
   270  }