1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149# Tar-Overlay
A shell script which creates and manages named overlayfs mounts backed by the contents from tar files.
Note: this is a work in progress, so it is not stable yet.
## Example
Given a tar with a set of files, create two independent scratch 'instances' where you can add, modify,
and delete files that can be reverted on command:
1) install a tar, this becomes an immutable 'image':
```
[wagoodman@vm1 ~]$ tar-overlay install-image ~/Downloads/msgpack-python-0.4.6.tar.gz
[wagoodman@vm1 ~]$ tar-overlay list-images
msgpack-python-0.4.6
```
2) create a few instances and mount them:
```
[wagoodman@vm1 ~]$ tar-overlay create-overlay foo msgpack-python-0.4.6
[wagoodman@vm1 ~]$ tar-overlay create-overlay bar msgpack-python-0.4.6
[wagoodman@vm1 ~]$ tar-overlay list-overlays
scratch1
scratch2
[wagoodman@vm1 ~]$ tar-overlay mount-overlay foo
~/bin/tar-overlay/store/instances/foo/rootfs
[wagoodman@vm1 ~]$ tar-overlay mount-overlay bar
~/bin/tar-overlay/store/instances/bar/rootfs
```
Note: the output for each mount attempt is where the instance mountpoint is.
3) Make some changes in one of the instances (foo):
```
[wagoodman@vm1 ~]$ tree -L 1 ~/bin/tar-overlay/store/instances/foo/rootfs
~/bin/tar-overlay/store/instances/foo/rootfs
├── COPYING
├── msgpack
├── PKG-INFO
├── README.rst
├── setup.py
└── test
2 directories, 4 files
[wagoodman@vm1 ~]$ rm -rf ~/bin/tar-overlay/store/instances/foo/rootfs/test
```
Notice that we can query which files have changed:
```
[wagoodman@vm1 ~]$ tar-overlay show-changes foo
.
└── test
├── test_buffer.py
├── test_case.py
├── test_except.py
├── test_extension.py
├── test_format.py
├── test_limits.py
├── test_newspec.py
├── test_obj.py
├── test_pack.py
├── test_read_size.py
├── test_seq.py
├── test_sequnpack.py
├── test_subtype.py
├── test_unpack.py
└── test_unpack_raw.py
1 directories, 15 files
```
Also notice that the other instance (bar) still has the original file:
```
[wagoodman@vm1 ~]$ tree -L 1 ~/bin/tar-overlay/store/instances/bar/rootfs
~/bin/tar-overlay/store/instances/bar/rootfs
├── COPYING
├── msgpack
├── PKG-INFO
├── README.rst
├── setup.py
└── test
2 directories, 4 files
[wagoodman@vm1 ~]$ rm -rf ~/bin/tar-overlay/store/instances/bar/rootfs/test
```
(See, the 'test' dir is still there)
4) Restore the 'foo' instance back to the original contents from the tar:
```
[wagoodman@vm1 ~]$ tar-overlay reset-overlay foo
[wagoodman@vm1 ~]$ tree -L 1 ~/bin/tar-overlay/store/instances/foo/rootfs
~/bin/tar-overlay/store/instances/foo/rootfs
├── COPYING
├── msgpack
├── PKG-INFO
├── README.rst
├── setup.py
└── test
2 directories, 4 files
```
# Motivation
The motivation for this was to take a read-only directory tree and make several
read-write 'instances' of that directory tree, where changes made in each instance would
not affect files in the other instances. Furthermore, there were benefits with
having the functionality to restore any instance to the original directory tree,
as if no modifications were done. This could all be done by making copies of the
tar contents for each instance, however, some of these directory trees were 1 GB
or more in size and only a few files are modified between all of the instances.
Docker provides almost the same functionality via dockerfiles, however, I am
not using docker for this project... so building and managing images this way seemed
awkward if I wasn't planning to use docker for containers. Instead, since overlayfs
has been integrated into the kernel and a wrapper script seemed simple enough to
make, tar-overlay was born!
# Usage
```
tar-overlay [command] [options]
Image commands:
install-image <tar-file> Take the given tar and make it available as in immutable image.
list-images List all known images.
Overlay Commands:
create <name> <image-name> Instantiate an image (make an instance).
list List image instantiations.
mount <name> Mount an instantiation for use.
mount-all Mount all overlays.
info <name> Show all information regardin the given overlay name.
rename <name> <new name> Rename the given instantiation.
reset <name> Undo all changes made to original image.
show-changes <name> Show a tree of all modified files
status <name> Shows if the given overlay is mounted.
umount <name> Unmount an instantiation.
umount-all Unmount all overlays.
Future Commands:
rename-image <iamge-name> Rename the given image.
delete-image <image-name> Delete the given image.
mount-image Mounts an image directly (not advised).
umount-image Unmounts a directly mounted image.
delete <name> Delete the given instantiation.
```