podman

1
//go:build !remote
2

3
package libpod
4

5
import (
6
	"time"
7

8
	"github.com/containers/podman/v5/libpod/define"
9
	"github.com/containers/podman/v5/libpod/lock"
10
	"github.com/containers/podman/v5/libpod/plugin"
11
	"github.com/containers/storage/pkg/directory"
12
)
13

14
// Volume is a libpod named volume.
15
// Named volumes may be shared by multiple containers, and may be created using
16
// more complex options than normal bind mounts. They may be backed by a mounted
17
// filesystem on the host.
18
type Volume struct {
19
	config *VolumeConfig
20
	state  *VolumeState
21

22
	ignoreIfExists bool
23
	valid          bool
24
	plugin         *plugin.VolumePlugin
25
	runtime        *Runtime
26
	lock           lock.Locker
27
}
28

29
// VolumeConfig holds the volume's immutable configuration.
30
type VolumeConfig struct {
31
	// Name of the volume.
32
	Name string `json:"name"`
33
	// ID of the volume's lock.
34
	LockID uint32 `json:"lockID"`
35
	// Labels for the volume.
36
	Labels map[string]string `json:"labels"`
37
	// The volume driver. Empty string or local does not activate a volume
38
	// driver, all other values will.
39
	Driver string `json:"volumeDriver"`
40
	// The location the volume is mounted at.
41
	MountPoint string `json:"mountPoint"`
42
	// Time the volume was created.
43
	CreatedTime time.Time `json:"createdAt,omitempty"`
44
	// Options to pass to the volume driver. For the local driver, this is
45
	// a list of mount options. For other drivers, they are passed to the
46
	// volume driver handling the volume.
47
	Options map[string]string `json:"volumeOptions,omitempty"`
48
	// Whether this volume is anonymous (will be removed on container exit)
49
	IsAnon bool `json:"isAnon"`
50
	// UID the volume will be created as.
51
	UID int `json:"uid"`
52
	// GID the volume will be created as.
53
	GID int `json:"gid"`
54
	// Size maximum of the volume.
55
	Size uint64 `json:"size"`
56
	// Inodes maximum of the volume.
57
	Inodes uint64 `json:"inodes"`
58
	// DisableQuota indicates that the volume should completely disable using any
59
	// quota tracking.
60
	DisableQuota bool `json:"disableQuota,omitempty"`
61
	// Timeout allows users to override the default driver timeout of 5 seconds
62
	Timeout *uint `json:"timeout,omitempty"`
63
	// StorageName is the name of the volume in c/storage. Only used for
64
	// image volumes.
65
	StorageName string `json:"storageName,omitempty"`
66
	// StorageID is the ID of the volume in c/storage. Only used for image
67
	// volumes.
68
	StorageID string `json:"storageID,omitempty"`
69
	// StorageImageID is the ID of the image the volume was based off of.
70
	// Only used for image volumes.
71
	StorageImageID string `json:"storageImageID,omitempty"`
72
	// MountLabel is the SELinux label to assign to mount points
73
	MountLabel string `json:"mountlabel,omitempty"`
74
}
75

76
// VolumeState holds the volume's mutable state.
77
// Volumes are not guaranteed to have a state. Only volumes using the Local
78
// driver that have mount options set will create a state.
79
type VolumeState struct {
80
	// Mountpoint is the location where the volume was mounted.
81
	// This is only used for volumes using a volume plugin, which will mount
82
	// at non-standard locations.
83
	MountPoint string `json:"mountPoint,omitempty"`
84
	// MountCount is the number of times this volume has been requested to
85
	// be mounted.
86
	// It is incremented on mount() and decremented on unmount().
87
	// On incrementing from 0, the volume will be mounted on the host.
88
	// On decrementing to 0, the volume will be unmounted on the host.
89
	MountCount uint `json:"mountCount"`
90
	// NeedsCopyUp indicates that the next time the volume is mounted into
91
	// a container, the container will "copy up" the contents of the
92
	// mountpoint into the volume.
93
	// This should only be done once. As such, this is set at container
94
	// create time, then cleared after the copy up is done and never set
95
	// again.
96
	NeedsCopyUp bool `json:"notYetMounted,omitempty"`
97
	// NeedsChown indicates that the next time the volume is mounted into
98
	// a container, the container will chown the volume to the container process
99
	// UID/GID.
100
	NeedsChown bool `json:"notYetChowned,omitempty"`
101
	// UIDChowned is the UID the volume was chowned to.
102
	UIDChowned int `json:"uidChowned,omitempty"`
103
	// GIDChowned is the GID the volume was chowned to.
104
	GIDChowned int `json:"gidChowned,omitempty"`
105
}
106

107
// Name retrieves the volume's name
108
func (v *Volume) Name() string {
109
	return v.config.Name
110
}
111

112
// Returns the size on disk of volume
113
func (v *Volume) Size() (uint64, error) {
114
	size, err := directory.Size(v.config.MountPoint)
115
	return uint64(size), err
116
}
117

118
// Driver retrieves the volume's driver.
119
func (v *Volume) Driver() string {
120
	return v.config.Driver
121
}
122

123
// Scope retrieves the volume's scope.
124
// Libpod does not implement volume scoping, and this is provided solely for
125
// Docker compatibility. It returns only "local".
126
func (v *Volume) Scope() string {
127
	return "local"
128
}
129

130
// Labels returns the volume's labels
131
func (v *Volume) Labels() map[string]string {
132
	labels := make(map[string]string)
133
	for key, value := range v.config.Labels {
134
		labels[key] = value
135
	}
136
	return labels
137
}
138

139
// MountPoint returns the volume's mountpoint on the host
140
func (v *Volume) MountPoint() (string, error) {
141
	// For the sake of performance, avoid locking unless we have to.
142
	if v.UsesVolumeDriver() || v.config.Driver == define.VolumeDriverImage {
143
		v.lock.Lock()
144
		defer v.lock.Unlock()
145

146
		if err := v.update(); err != nil {
147
			return "", err
148
		}
149
	}
150

151
	return v.mountPoint(), nil
152
}
153

154
// MountCount returns the volume's mountcount on the host from state
155
// Useful in determining if volume is using plugin or a filesystem mount and its mount
156
func (v *Volume) MountCount() (uint, error) {
157
	v.lock.Lock()
158
	defer v.lock.Unlock()
159
	if err := v.update(); err != nil {
160
		return 0, err
161
	}
162
	return v.state.MountCount, nil
163
}
164

165
// Internal-only helper for volume mountpoint
166
func (v *Volume) mountPoint() string {
167
	if v.UsesVolumeDriver() || v.config.Driver == define.VolumeDriverImage {
168
		return v.state.MountPoint
169
	}
170

171
	return v.config.MountPoint
172
}
173

174
// Options return the volume's options
175
func (v *Volume) Options() map[string]string {
176
	options := make(map[string]string)
177
	for k, v := range v.config.Options {
178
		options[k] = v
179
	}
180
	return options
181
}
182

183
// Anonymous returns whether this volume is anonymous. Anonymous volumes were
184
// created with a container, and will be removed when that container is removed.
185
func (v *Volume) Anonymous() bool {
186
	return v.config.IsAnon
187
}
188

189
// UID returns the UID the volume will be created as.
190
func (v *Volume) UID() (int, error) {
191
	v.lock.Lock()
192
	defer v.lock.Unlock()
193

194
	if err := v.update(); err != nil {
195
		return -1, err
196
	}
197

198
	return v.uid(), nil
199
}
200

201
// Internal, unlocked accessor for UID.
202
func (v *Volume) uid() int {
203
	if v.state.UIDChowned > 0 {
204
		return v.state.UIDChowned
205
	}
206
	return v.config.UID
207
}
208

209
// GID returns the GID the volume will be created as.
210
func (v *Volume) GID() (int, error) {
211
	v.lock.Lock()
212
	defer v.lock.Unlock()
213

214
	if err := v.update(); err != nil {
215
		return -1, err
216
	}
217

218
	return v.gid(), nil
219
}
220

221
// Internal, unlocked accessor for GID.
222
func (v *Volume) gid() int {
223
	if v.state.GIDChowned > 0 {
224
		return v.state.GIDChowned
225
	}
226
	return v.config.GID
227
}
228

229
// CreatedTime returns the time the volume was created at. It was not tracked
230
// for some time, so older volumes may not contain one.
231
func (v *Volume) CreatedTime() time.Time {
232
	return v.config.CreatedTime
233
}
234

235
// Config returns the volume's configuration.
236
func (v *Volume) Config() (*VolumeConfig, error) {
237
	config := VolumeConfig{}
238
	err := JSONDeepCopy(v.config, &config)
239
	return &config, err
240
}
241

242
// VolumeInUse goes through the container dependencies of a volume
243
// and checks if the volume is being used by any container.
244
func (v *Volume) VolumeInUse() ([]string, error) {
245
	v.lock.Lock()
246
	defer v.lock.Unlock()
247

248
	if !v.valid {
249
		return nil, define.ErrVolumeRemoved
250
	}
251
	return v.runtime.state.VolumeInUse(v)
252
}
253

254
// IsDangling returns whether this volume is dangling (unused by any
255
// containers).
256
func (v *Volume) IsDangling() (bool, error) {
257
	ctrs, err := v.VolumeInUse()
258
	if err != nil {
259
		return false, err
260
	}
261
	return len(ctrs) == 0, nil
262
}
263

264
// UsesVolumeDriver determines whether the volume uses a volume driver. Volume
265
// drivers are pluggable backends for volumes that will manage the storage and
266
// mounting.
267
func (v *Volume) UsesVolumeDriver() bool {
268
	if v.config.Driver == define.VolumeDriverImage {
269
		if _, ok := v.runtime.config.Engine.VolumePlugins[v.config.Driver]; ok {
270
			return true
271
		}
272
		return false
273
	}
274
	return !(v.config.Driver == define.VolumeDriverLocal || v.config.Driver == "")
275
}
276

277
func (v *Volume) Mount() (string, error) {
278
	v.lock.Lock()
279
	defer v.lock.Unlock()
280
	err := v.mount()
281
	return v.config.MountPoint, err
282
}
283

284
func (v *Volume) Unmount() error {
285
	v.lock.Lock()
286
	defer v.lock.Unlock()
287
	return v.unmount(false)
288
}
289

290
func (v *Volume) NeedsMount() bool {
291
	return v.needsMount()
292
}
293