github.com/moby/docker@v26.1.3+incompatible/volume/local/local.go (about) 1 // Package local provides the default implementation for volumes. It 2 // is used to mount data volume containers and directories local to 3 // the host server. 4 package local // import "github.com/docker/docker/volume/local" 5 6 import ( 7 "context" 8 "encoding/json" 9 "os" 10 "path/filepath" 11 "reflect" 12 "runtime/debug" 13 "strings" 14 "sync" 15 16 "github.com/containerd/log" 17 "github.com/docker/docker/daemon/names" 18 "github.com/docker/docker/errdefs" 19 "github.com/docker/docker/pkg/idtools" 20 "github.com/docker/docker/quota" 21 "github.com/docker/docker/volume" 22 "github.com/pkg/errors" 23 ) 24 25 const ( 26 // volumeDataPathName is the name of the directory where the volume data is stored. 27 // It uses a very distinctive name to avoid collisions migrating data between 28 // Docker versions. 29 volumeDataPathName = "_data" 30 volumesPathName = "volumes" 31 ) 32 33 var ( 34 // ErrNotFound is the typed error returned when the requested volume name can't be found 35 ErrNotFound = errors.New("volume not found") 36 // volumeNameRegex ensures the name assigned for the volume is valid. 37 // This name is used to create the bind directory, so we need to avoid characters that 38 // would make the path to escape the root directory. 39 volumeNameRegex = names.RestrictedNamePattern 40 41 _ volume.LiveRestorer = (*localVolume)(nil) 42 ) 43 44 type activeMount struct { 45 count uint64 46 mounted bool 47 } 48 49 // New instantiates a new Root instance with the provided scope. Scope 50 // is the base path that the Root instance uses to store its 51 // volumes. The base path is created here if it does not exist. 52 func New(scope string, rootIdentity idtools.Identity) (*Root, error) { 53 r := &Root{ 54 path: filepath.Join(scope, volumesPathName), 55 volumes: make(map[string]*localVolume), 56 rootIdentity: rootIdentity, 57 } 58 59 if err := idtools.MkdirAllAndChown(r.path, 0o701, idtools.CurrentIdentity()); err != nil { 60 return nil, err 61 } 62 63 dirs, err := os.ReadDir(r.path) 64 if err != nil { 65 return nil, err 66 } 67 68 if r.quotaCtl, err = quota.NewControl(r.path); err != nil { 69 log.G(context.TODO()).Debugf("No quota support for local volumes in %s: %v", r.path, err) 70 } 71 72 for _, d := range dirs { 73 if !d.IsDir() { 74 continue 75 } 76 77 name := d.Name() 78 v := &localVolume{ 79 driverName: r.Name(), 80 name: name, 81 rootPath: filepath.Join(r.path, name), 82 path: filepath.Join(r.path, name, volumeDataPathName), 83 quotaCtl: r.quotaCtl, 84 } 85 86 if err := v.loadOpts(); err != nil { 87 return nil, err 88 } 89 90 if err := v.restoreIfMounted(); err != nil { 91 log.G(context.TODO()).WithFields(log.Fields{ 92 "volume": v.name, 93 "path": v.path, 94 "error": err, 95 }).Warn("restoreIfMounted failed") 96 } 97 98 r.volumes[name] = v 99 } 100 101 return r, nil 102 } 103 104 // Root implements the Driver interface for the volume package and 105 // manages the creation/removal of volumes. It uses only standard vfs 106 // commands to create/remove dirs within its provided scope. 107 type Root struct { 108 m sync.Mutex 109 path string 110 quotaCtl *quota.Control 111 volumes map[string]*localVolume 112 rootIdentity idtools.Identity 113 } 114 115 // List lists all the volumes 116 func (r *Root) List() ([]volume.Volume, error) { 117 var ls []volume.Volume 118 r.m.Lock() 119 for _, v := range r.volumes { 120 ls = append(ls, v) 121 } 122 r.m.Unlock() 123 return ls, nil 124 } 125 126 // Name returns the name of Root, defined in the volume package in the DefaultDriverName constant. 127 func (r *Root) Name() string { 128 return volume.DefaultDriverName 129 } 130 131 // Create creates a new volume.Volume with the provided name, creating 132 // the underlying directory tree required for this volume in the 133 // process. 134 func (r *Root) Create(name string, opts map[string]string) (volume.Volume, error) { 135 if err := r.validateName(name); err != nil { 136 return nil, err 137 } 138 if err := r.validateOpts(opts); err != nil { 139 return nil, err 140 } 141 142 r.m.Lock() 143 defer r.m.Unlock() 144 145 v, exists := r.volumes[name] 146 if exists { 147 return v, nil 148 } 149 150 v = &localVolume{ 151 driverName: r.Name(), 152 name: name, 153 rootPath: filepath.Join(r.path, name), 154 path: filepath.Join(r.path, name, volumeDataPathName), 155 quotaCtl: r.quotaCtl, 156 } 157 158 // Root dir does not need to be accessed by the remapped root 159 if err := idtools.MkdirAllAndChown(v.rootPath, 0o701, idtools.CurrentIdentity()); err != nil { 160 return nil, errors.Wrapf(errdefs.System(err), "error while creating volume root path '%s'", v.rootPath) 161 } 162 163 // Remapped root does need access to the data path 164 if err := idtools.MkdirAllAndChown(v.path, 0o755, r.rootIdentity); err != nil { 165 return nil, errors.Wrapf(errdefs.System(err), "error while creating volume data path '%s'", v.path) 166 } 167 168 var err error 169 defer func() { 170 if err != nil { 171 os.RemoveAll(v.rootPath) 172 } 173 }() 174 175 if err = v.setOpts(opts); err != nil { 176 return nil, err 177 } 178 179 r.volumes[name] = v 180 return v, nil 181 } 182 183 // Remove removes the specified volume and all underlying data. If the 184 // given volume does not belong to this driver and an error is 185 // returned. The volume is reference counted, if all references are 186 // not released then the volume is not removed. 187 func (r *Root) Remove(v volume.Volume) error { 188 r.m.Lock() 189 defer r.m.Unlock() 190 191 lv, ok := v.(*localVolume) 192 if !ok { 193 return errdefs.System(errors.Errorf("unknown volume type %T", v)) 194 } 195 196 if lv.active.count > 0 { 197 return errdefs.System(errors.New("volume has active mounts")) 198 } 199 200 if err := lv.unmount(); err != nil { 201 return err 202 } 203 204 // TODO(thaJeztah) is there a reason we're evaluating the data-path here, and not the volume's rootPath? 205 realPath, err := filepath.EvalSymlinks(lv.path) 206 if err != nil { 207 if !os.IsNotExist(err) { 208 return err 209 } 210 // if the volume's data-directory wasn't found, fall back to using the 211 // volume's root path (see 8d27417bfeff316346d00c07a456b0e1b056e788) 212 realPath = lv.rootPath 213 } 214 215 if realPath == r.path || !strings.HasPrefix(realPath, r.path) { 216 return errdefs.System(errors.Errorf("unable to remove a directory outside of the local volume root %s: %s", r.path, realPath)) 217 } 218 219 if err := removePath(realPath); err != nil { 220 return err 221 } 222 223 delete(r.volumes, lv.name) 224 return removePath(lv.rootPath) 225 } 226 227 func removePath(path string) error { 228 if err := os.RemoveAll(path); err != nil { 229 if os.IsNotExist(err) { 230 return nil 231 } 232 return errdefs.System(errors.Wrapf(err, "error removing volume path '%s'", path)) 233 } 234 return nil 235 } 236 237 // Get looks up the volume for the given name and returns it if found 238 func (r *Root) Get(name string) (volume.Volume, error) { 239 r.m.Lock() 240 v, exists := r.volumes[name] 241 r.m.Unlock() 242 if !exists { 243 return nil, ErrNotFound 244 } 245 return v, nil 246 } 247 248 // Scope returns the local volume scope 249 func (r *Root) Scope() string { 250 return volume.LocalScope 251 } 252 253 func (r *Root) validateName(name string) error { 254 if len(name) == 1 { 255 return errdefs.InvalidParameter(errors.New("volume name is too short, names should be at least two alphanumeric characters")) 256 } 257 if !volumeNameRegex.MatchString(name) { 258 return errdefs.InvalidParameter(errors.Errorf("%q includes invalid characters for a local volume name, only %q are allowed. If you intended to pass a host directory, use absolute path", name, names.RestrictedNameChars)) 259 } 260 return nil 261 } 262 263 // localVolume implements the Volume interface from the volume package and 264 // represents the volumes created by Root. 265 type localVolume struct { 266 m sync.Mutex 267 // unique name of the volume 268 name string 269 // rootPath is the volume's root path, where the volume's metadata is stored. 270 rootPath string 271 // path is the path on the host where the data lives 272 path string 273 // driverName is the name of the driver that created the volume. 274 driverName string 275 // opts is the parsed list of options used to create the volume 276 opts *optsConfig 277 // active refcounts the active mounts 278 active activeMount 279 // reference to Root instances quotaCtl 280 quotaCtl *quota.Control 281 } 282 283 // Name returns the name of the given Volume. 284 func (v *localVolume) Name() string { 285 return v.name 286 } 287 288 // DriverName returns the driver that created the given Volume. 289 func (v *localVolume) DriverName() string { 290 return v.driverName 291 } 292 293 // Path returns the data location. 294 func (v *localVolume) Path() string { 295 return v.path 296 } 297 298 // CachedPath returns the data location 299 func (v *localVolume) CachedPath() string { 300 return v.path 301 } 302 303 // Mount implements the localVolume interface, returning the data location. 304 // If there are any provided mount options, the resources will be mounted at this point 305 func (v *localVolume) Mount(id string) (string, error) { 306 v.m.Lock() 307 defer v.m.Unlock() 308 logger := log.G(context.TODO()).WithField("volume", v.name) 309 if v.needsMount() { 310 if !v.active.mounted { 311 logger.Debug("Mounting volume") 312 if err := v.mount(); err != nil { 313 return "", errdefs.System(err) 314 } 315 v.active.mounted = true 316 } 317 v.active.count++ 318 logger.WithField("active mounts", v.active).Debug("Incremented active mount count") 319 } 320 if err := v.postMount(); err != nil { 321 return "", err 322 } 323 return v.path, nil 324 } 325 326 // Unmount dereferences the id, and if it is the last reference will unmount any resources 327 // that were previously mounted. 328 func (v *localVolume) Unmount(id string) error { 329 v.m.Lock() 330 defer v.m.Unlock() 331 logger := log.G(context.TODO()).WithField("volume", v.name) 332 333 // Always decrement the count, even if the unmount fails 334 // Essentially docker doesn't care if this fails, it will send an error, but 335 // ultimately there's nothing that can be done. If we don't decrement the count 336 // this volume can never be removed until a daemon restart occurs. 337 if v.needsMount() { 338 // TODO: Remove once the real bug is fixed: https://github.com/moby/moby/issues/46508 339 if v.active.count > 0 { 340 v.active.count-- 341 logger.WithField("active mounts", v.active).Debug("Decremented active mount count") 342 } else { 343 logger.Error("An attempt to decrement a zero mount count") 344 logger.Error(string(debug.Stack())) 345 return nil 346 } 347 } 348 349 if v.active.count > 0 { 350 return nil 351 } 352 353 if !v.active.mounted { 354 return nil 355 } 356 357 logger.Debug("Unmounting volume") 358 return v.unmount() 359 } 360 361 func (v *localVolume) Status() map[string]interface{} { 362 return nil 363 } 364 365 func (v *localVolume) loadOpts() error { 366 b, err := os.ReadFile(filepath.Join(v.rootPath, "opts.json")) 367 if err != nil { 368 if !errors.Is(err, os.ErrNotExist) { 369 log.G(context.TODO()).WithError(err).Warnf("error while loading volume options for volume: %s", v.name) 370 } 371 return nil 372 } 373 opts := optsConfig{} 374 if err := json.Unmarshal(b, &opts); err != nil { 375 return errors.Wrapf(err, "error while unmarshaling volume options for volume: %s", v.name) 376 } 377 // Make sure this isn't an empty optsConfig. 378 // This could be empty due to buggy behavior in older versions of Docker. 379 if !reflect.DeepEqual(opts, optsConfig{}) { 380 v.opts = &opts 381 } 382 return nil 383 } 384 385 func (v *localVolume) saveOpts() error { 386 var b []byte 387 b, err := json.Marshal(v.opts) 388 if err != nil { 389 return err 390 } 391 err = os.WriteFile(filepath.Join(v.rootPath, "opts.json"), b, 0o600) 392 if err != nil { 393 return errdefs.System(errors.Wrap(err, "error while persisting volume options")) 394 } 395 return nil 396 } 397 398 // LiveRestoreVolume restores reference counts for mounts 399 // It is assumed that the volume is already mounted since this is only called for active, live-restored containers. 400 func (v *localVolume) LiveRestoreVolume(ctx context.Context, _ string) error { 401 v.m.Lock() 402 defer v.m.Unlock() 403 404 if !v.needsMount() { 405 return nil 406 } 407 v.active.count++ 408 v.active.mounted = true 409 log.G(ctx).WithFields(log.Fields{ 410 "volume": v.name, 411 "active mounts": v.active, 412 }).Debugf("Live restored volume") 413 return nil 414 } 415 416 // getAddress finds out address/hostname from options 417 func getAddress(opts string) string { 418 for _, opt := range strings.Split(opts, ",") { 419 if strings.HasPrefix(opt, "addr=") { 420 return strings.TrimPrefix(opt, "addr=") 421 } 422 } 423 return "" 424 } 425 426 // getPassword finds out a password from options 427 func getPassword(opts string) string { 428 for _, opt := range strings.Split(opts, ",") { 429 if strings.HasPrefix(opt, "password=") { 430 return strings.TrimPrefix(opt, "password=") 431 } 432 } 433 return "" 434 }