Skip to content

Commit b3e2a8c

Browse files
mbshieldsmbshields
authored
Docs mishield cli (#45)
* docs: document stacker CLI commands Signed-off-by: mbshields <mshields@alum.mit.edu> * docs: document stacker CLI commands (fix xrefs) Signed-off-by: mbshields <mshields@alum.mit.edu> --------- Signed-off-by: mbshields <mshields@alum.mit.edu>
1 parent e15ab9c commit b3e2a8c

1 file changed

Lines changed: 233 additions & 1 deletion

File tree

‎docs/reference/stacker_cli.md‎

Lines changed: 233 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1 +1,233 @@
1-
# Stacker CLI
1+
# Stacker Command-Line Interface Reference
2+
3+
<table>
4+
<tr><td><a href="#stacker">stacker</a></td><td>Stacker builds OCI images</td></tr>
5+
<tr><td><a href="#stacker-build">stacker build</a></td><td>Build a new OCI image from a stacker yaml file</td></tr>
6+
<tr><td><a href="#stacker-recursive-build">stacker recursive-build</a></td><td>Find stacker yaml files under a directory and builds all OCI layers they define</td></tr>
7+
<tr><td><a href="#stacker-publish">stacker publish</a></td><td>Publish OCI images previously built from one or more stacker yaml files</td></tr>
8+
<tr><td><a href="#stacker-chroot-exec">stacker chroot</a></td><td>Run a command in a chroot (same as <code>stacker exec</code>)</td></tr>
9+
<tr><td><a href="#stacker-clean">stacker clean</a></td><td>Clean up after a stacker build</td></tr>
10+
<tr><td><a href="#stacker-inspect">stacker inspect</a></td><td>Print the json representation of an OCI image</td></tr>
11+
<tr><td><a href="#stacker-grab">stacker grab</a></td><td>Grab a file from the layer's filesystem</td></tr>
12+
<tr><td><a href="#stacker-unpriv-setup">stacker unpriv-setup</a></td><td>Do the necessary unprivileged setup for stacker build to work without root</td></tr>
13+
<tr><td><a href="#stacker-gc">stacker gc</a></td><td>Garbage collection of unused OCI imports/outputs snapshots</td></tr>
14+
<tr><td><a href="#stacker-check">stacker check</a></td><td>Check that all runtime required items (like kernel features) are present</td></tr>
15+
<tr><td><a href="#stacker-help">stacker help</a></td><td>Show a list of commands or help for one command</td></tr>
16+
</table>
17+
18+
<a name="stacker"></a>
19+
20+
## stacker
21+
22+
NAME:
23+
stacker - stacker builds OCI images
24+
25+
USAGE:
26+
stacker [global options] command [command options] [arguments...]
27+
28+
VERSION:
29+
stacker v0.40.1-e54a685 liblxc a330126b45c7c3b6fcf0f9ba6c1eda7bdb4e508a
30+
31+
COMMANDS:
32+
build builds a new OCI image from a stacker yaml file
33+
recursive-build finds stacker yaml files under a directory and builds all OCI layers they define
34+
publish publishes OCI images previously built from one or more stacker yaml files
35+
chroot, exec run a command in a chroot
36+
clean cleans up after a `stacker build`
37+
inspect print the json representation of an OCI image
38+
grab grabs a file from the layer's filesystem
39+
unpriv-setup do the necessary unprivileged setup for stacker build to work without root
40+
gc gc unused OCI imports/outputs snapshots
41+
check checks that all runtime required things (like kernel features) are present
42+
help, h Shows a list of commands or help for one command
43+
44+
GLOBAL OPTIONS:
45+
--stacker-dir value set the directory for stacker's cache (default: ".stacker")
46+
--oci-dir value set the directory for OCI output (default: "oci")
47+
--roots-dir value set the directory for the rootfs output (default: "roots")
48+
--config value stacker config file with defaults (default: "/users/mishield/.config/stacker/conf.yaml")
49+
--debug enable stacker debug mode
50+
-q, --quiet silence all logs
51+
--log-file value log to a file instead of stderr
52+
--log-timestamp whether to log a timestamp prefix
53+
--storage-type value storage type (must be "overlay", left for compatibility) (default: "overlay")
54+
--no-progress disable progress when downloading container images or files
55+
--help, -h show help
56+
--version, -v print the version
57+
58+
<a name="stacker-build"></a>
59+
60+
## stacker build
61+
62+
NAME:
63+
stacker build - builds a new OCI image from a stacker yaml file
64+
65+
USAGE:
66+
stacker build [command options] [arguments...]
67+
68+
OPTIONS:
69+
--no-cache don't use the previous build cache
70+
--substitute value variable substitution in stackerfiles, FOO=bar format
71+
--substitute-file value file containing variable substitution in stackerfiles, 'FOO: bar' yaml format
72+
--on-run-failure value command to run inside container if run fails (useful for inspection)
73+
--shell-fail exec /bin/sh inside the container if run fails (alias for --on-run-failure=/bin/sh)
74+
--layer-type value set the output layer type (supported values: tar, squashfs); can be supplied multiple times (default: "tar")
75+
--no-squashfs-verity do not append dm-verity data to squashfs archives
76+
--require-hash require all remote imports to have a hash provided in stackerfiles
77+
--order-only show the build order without running the actual build
78+
--annotations-namespace value set OCI annotations namespace in the OCI image manifest (default: "io.stackeroci")
79+
--stacker-file value, -f value the input stackerfile (default: "stacker.yaml")
80+
81+
<a name="stacker-recursive-build"></a>
82+
83+
## stacker recursive-build
84+
85+
NAME:
86+
stacker recursive-build - finds stacker yaml files under a directory and builds all OCI layers they define
87+
88+
USAGE:
89+
stacker recursive-build [command options] [arguments...]
90+
91+
OPTIONS:
92+
--no-cache don't use the previous build cache
93+
--substitute value variable substitution in stackerfiles, FOO=bar format
94+
--substitute-file value file containing variable substitution in stackerfiles, 'FOO: bar' yaml format
95+
--on-run-failure value command to run inside container if run fails (useful for inspection)
96+
--shell-fail exec /bin/sh inside the container if run fails (alias for --on-run-failure=/bin/sh)
97+
--layer-type value set the output layer type (supported values: tar, squashfs); can be supplied multiple times (default: "tar")
98+
--no-squashfs-verity do not append dm-verity data to squashfs archives
99+
--require-hash require all remote imports to have a hash provided in stackerfiles
100+
--order-only show the build order without running the actual build
101+
--annotations-namespace value set OCI annotations namespace in the OCI image manifest (default: "io.stackeroci")
102+
--stacker-file-pattern value, -p value regex pattern to use when searching for stackerfile paths (default: "\\/stacker.yaml$")
103+
--search-dir value, -d value directory under which to search for stackerfiles to build (default: ".")
104+
105+
<a name="stacker-publish"></a>
106+
107+
## stacker publish
108+
109+
NAME:
110+
stacker publish - publishes OCI images previously built from one or more stacker yaml files
111+
112+
USAGE:
113+
stacker publish [command options] [arguments...]
114+
115+
OPTIONS:
116+
--stacker-file value, -f value the input stackerfile (default: "stacker.yaml")
117+
--stacker-file-pattern value, -p value regex pattern to use when searching for stackerfile paths (default: "\\/stacker.yaml$")
118+
--search-dir value, -d value directory under which to search for stackerfiles to publish
119+
--url value url where to publish the OCI images
120+
--username value username for the registry where the OCI images are published
121+
--password value password for the registry where the OCI images are published
122+
--skip-tls skip tls verify on upstream registry
123+
--tag value tag to be used when publishing
124+
--substitute value variable substitution in stackerfiles, FOO=bar format
125+
--show-only show the images to be published without actually publishing them
126+
--force force publishing the images present in the OCI layout even if they should be rebuilt
127+
--layer-type value set the output layer type (supported values: tar, squashfs); can be supplied multiple times (default: "tar")
128+
129+
<a name="stacker-chroot-exec"></a>
130+
131+
## stacker chroot, exec
132+
133+
NAME:
134+
stacker chroot - run a command in a chroot
135+
136+
USAGE:
137+
stacker chroot [command options] [tag] [cmd]
138+
139+
<tag> is the built tag in the stackerfile to chroot to, or the first tag if
140+
none is specified.
141+
142+
<cmd> is the command to run, or /bin/sh if none is specified. To specify cmd,
143+
you must specify a tag.
144+
145+
OPTIONS:
146+
--stacker-file value, -f value the input stackerfile (default: "stacker.yaml")
147+
--substitute value variable substitution in stackerfiles, FOO=bar format
148+
149+
<a name="stacker-clean"></a>
150+
151+
## stacker clean
152+
153+
NAME:
154+
stacker clean - cleans up after a `stacker build`
155+
156+
USAGE:
157+
stacker clean [command options] [arguments...]
158+
159+
OPTIONS:
160+
--all no-op; this used to do soemthing, and is left in for compatibility
161+
162+
<a name="stacker-inspect"></a>
163+
164+
## stacker inspect
165+
166+
NAME:
167+
stacker inspect - print the json representation of an OCI image
168+
169+
USAGE:
170+
stacker inspect [tag]
171+
172+
<tag> is the tag in the stackerfile to inspect. If none is supplied, inspect
173+
prints the information on all tags.
174+
175+
<a name="stacker-grab"></a>
176+
177+
## stacker grab
178+
179+
NAME:
180+
stacker grab - grabs a file from the layer's filesystem
181+
182+
USAGE:
183+
stacker grab <tag>:<path>
184+
185+
<tag> is the tag in a built stacker image to extract the file from.
186+
187+
<path> is the path to extract (relative to /) in the image's rootfs.
188+
189+
<a name="stacker-unpriv-setup"></a>
190+
191+
## stacker unpriv-setup
192+
193+
NAME:
194+
stacker unpriv-setup - do the necessary unprivileged setup for stacker build to work without root
195+
196+
USAGE:
197+
stacker unpriv-setup [command options] [arguments...]
198+
199+
OPTIONS:
200+
--uid value the user to do setup for (defaults to $SUDO_UID from env)
201+
--gid value the group to do setup for (defaults to $SUDO_GID from env)
202+
--username value the username to do setup for (defaults to $SUDO_USER from env)
203+
204+
<a name="stacker-gc"></a>
205+
206+
## stacker gc
207+
208+
NAME:
209+
stacker gc - gc unused OCI imports/outputs snapshots
210+
211+
USAGE:
212+
stacker gc [arguments...]
213+
214+
<a name="stacker-check"></a>
215+
216+
## stacker check
217+
218+
NAME:
219+
stacker check - checks that all runtime required things (like kernel features) are present
220+
221+
USAGE:
222+
stacker check [arguments...]
223+
224+
<a name="stacker-help"></a>
225+
226+
## stacker help
227+
228+
NAME:
229+
- Shows a list of commands or help for one command
230+
231+
USAGE:
232+
[command]
233+

0 commit comments

Comments
 (0)