1OCI(1) APRIL 2016 OCI(1)
2
6 ocitools-generate - Generate a config.json for an OCI container
7
11 ocitools generate [--arch[=[]] [--apparmor[=[]]] [--args[=[]]]
12 [--bind[=[]]] [--cap-add[=[]]] [--cap-drop[=[]]] [--cwd[=[]]]
13 [--env[=[]]] [--gid[=GID]] [--gidmappings[=[]]]] [--groups[=[]]]
14 [--hostname[=[]]] [--help] [--ipc] [--network] [--no-new-privileges]
15 [--mount] [--mount-cgroups] [--os[=[]]] [--pid] [--poststart[=[]]]
16 [--poststop[=[]]] [--prestart[=[]]] [--privileged] [--read-only]
17 [--root-propagation[=[]]] [--rootfs[=[]]] [--seccomp-default[=[]]]
18 [--seccomp-arch[=[]]] [--seccomp-syscalls[=[]]] [--selinux-label[=[]]]
19 [--sysctl[=[]]] [--tmpfs[=[]]] [--uid[=[]]] [--uidmappings[=[]]]
20 [--uts]
21
25 ocitools generate is used to generate a config.json (OCI spec file) to
26 be used to instantiate an OCI container. This config.json file can be
27 placed into a directory and used by an OCI compatable runtime like runc
28 to run a container.
29
33 --apparmor="PROFILE"
34 Specifies the the apparmor profile for the container
35 --arch="ARCH"
38 Architecture used within the container.
39 "amd64"
40 --args=OPTION
43 Arguments to run within the container. Can be specified multiple
44 times.
45 If you were going to run a command with multiple options, you would
46 need to specify the command and each argument in order.
47 --args "/usr/bin/httpd" --args "-D" --args "FOREGROUND"
50 --bind=[=[[HOST-DIR:CONTAINER-DIR][:OPTIONS]]] Bind mount
53 directories src:dest:(rw,ro) If you specify, --bind
54 /HOST-DIR:/CONTAINER-DIR, runc bind mounts /HOST-DIR in the host
55 to /CONTAINER-DIR in the OCI container. The OPTIONS are a comma
56 delimited list and can be: [rw|ro] The HOST_DIR and
57 CONTAINER-DIR must be absolute paths such as /src/docs. You
58 can add :ro or :rw suffix to a volume to mount it read-only or
59 read-write mode, respectively. By default, the volumes are mounted
60 read-write.
61 --cap-add=[]
64 Add Linux capabilities
65 --cap-drop=[]
68 Drop Linux capabilities
69 --cwd=PATH
72 Current working directory for the process
73 --env=[]
76 Set environment variables
77 This option allows you to specify arbitrary environment variables that
80 are available for the process that will be launched inside of the
81 container.
82 --hostname=""
85 Container host name
86 Sets the container host name that is available inside the container.
89 --help
92 Print usage statement
93 --gid=GID
96 Gid for the process inside of container
97 --groups=GROUP
100 Supplementary groups for the processes inside of container
101 --gidmappings=GIDMAPPINGS
104 Add GIDMappings e.g HostID:ContainerID:Size for use with User
105 Namespace
106 --ipc
109 Use ipc namespace
110 --network
113 Use network namespace
114 --no-new-privileges
117 Set no new privileges bit for the container process. Setting this
118 flag
119 will block the container processes from gaining any additional
120 privileges
121 using tools like setuid apps. It is a good idea to run unprivileged
122 containers with this flag.
123 --mount
126 Use a mount namespace
127 --mount-cgroups
130 Mount cgroups (rw,ro,no)
131 --os=OS
134 Operating system used within the container
135 --pid
138 Use a pid namespace
139 --poststart=CMD
142 Path to command to run in poststart hooks. This command will be run
143 before
144 the container process gets launched but after the container
145 environment and
146 main process has been created.
147 --poststop=CMD
150 Path to command to run in poststop hooks. This command will be run
151 after the
152 container completes but before the container process is destroyed
153 --prestart=CMD
156 Path to command to run in prestart hooks. This command will be run
157 before
158 the container process gets launched but after the container
159 environment.
160 --privileged=true|false
163 Give extended privileges to this container. The default is false.
164 By default, OCI containers are “unprivileged” (=false) and cannot do
167 some of the things a normal root process can do.
168 When the operator executes ocitools generate --privileged, OCI will
171 enable access to all devices on the host as well as disable some of the
172 confinement mechanisms like AppArmor, SELinux, and seccomp from
173 blocking access to privileged processes. This gives the container
174 processes nearly all the same access to the host as processes
175 generating outside of a container on the host.
176 --read-only=true|false
179 Mount the container's root filesystem as read only.
180 By default a container will have its root filesystem writable allowing
183 processes to write files anywhere. By specifying the --read-only flag
184 the container will have its root filesystem mounted as read only
185 prohibiting any writes.
186 --root-propagation=PROPOGATIONMODE
189 Mount propagation for root filesystem.
190 Values are "SHARED, RSHARED, PRIVATE, RPRIVATE, SLAVE, RSLAVE"
191 --rootfs="ROOTFSPATH"
194 Path to the rootfs
195 --sysctl=SYSCTLSETTING
198 Add sysctl settings e.g net.ipv4.forward=1, only allowed if the syctl
199 is
200 namespaced.
201 --seccomp-default=ACTION
204 Specifies the the defaultaction of Seccomp syscall restrictions
205 Values: KILL,ERRNO,TRACE,ALLOW
206 --seccomp-arch=ARCH
209 Specifies Additional architectures permitted to be used for system
210 calls.
211 By default if you turn on seccomp, only the host architecture will be
212 allowed.
213 --seccomp-syscalls=SYSCALLS
216 Specifies Additional syscalls permitted to be used for system calls,
217 e.g Name:Action:Arg1_index/Arg1_value/Arg1_valuetwo/Arg1_op,
218 Arg2_index/Arg2_value/Arg2_valuetwo/Arg2_op
219 --selinux-label=[=SELINUXLABEL]]
222 SELinux Label
223 Depending on your SELinux policy, you would specify a label that
224 looks like
225 this:
226 "system_u:system_r:svirt_lxc_net_t:s0:c1,c2"
227 Note you would want your ROOTFS directory to be labeled with a context that
230 this process type can use.
231 "system_u:object_r:usr_t:s0" might be a good label for a readonly container,
233 "system_u:system_r:svirt_sandbox_file_t:s0:c1,c2" for a read/write container.
234 --tmpfs=[] Create a tmpfs mount
238 Mount a temporary filesystem (tmpfs) mount into a container, for
239 example:
240 $ ocitools generate -d --tmpfs /tmp:rw,size=787448k,mode=1777 my_image
243 This command mounts a `tmpfs` at `/tmp` within the container. The supported mount options are the same as the Linux default `mount` flags. If you do not specify any options, the systems uses the following options:
245 `rw,noexec,nosuid,nodev,size=65536k`.
246 --uid=UID
250 Sets the UID used within the container.
251 --uidmappings
254 Add UIDMappings e.g HostUID:ContainerID:Size for use with User
255 Namespace
256 --uts
259 Use the uts namespace
260
265 During container image development, containers often need to write to
266 the image content. Installing packages into /usr, for example. In
267 production, applications seldom need to write to the image. Container
268 applications write to volumes if they need to write to file systems at
269 all. Applications can be made more secure by generating them in
270 read-only mode using the --read-only switch. This protects the
271 containers image from modification. Read only containers may still need
272 to write temporary data. The best way to handle this is to mount tmpfs
273 directories on /generate and /tmp.
274 # ocitools generate --read-only --tmpfs /generate --tmpfs /tmp --tmpfs /run --rootfs /var/lib/containers/fedora /bin/bash
277
281 If you want messages that are logged in your container to show up in
282 the host's syslog/journal then you should bind mount the /dev/log
283 directory as follows.
284 # ocitools generate --bind /dev/log:/dev/log --rootfs /var/lib/containers/fedora /bin/bash
287 From inside the container you can test this by sending a message to the
291 log.
292 (bash)# logger "Hello from my container"
295 Then exit and check the journal.
299 # exit
302 # journalctl -b | grep Hello
304 This should list the message sent to logger.
308
311 To mount a host directory as a container volume, specify the absolute
312 path to the directory and the absolute path for the container directory
313 separated by a colon:
314 # ocitools generate --bind /var/db:/data1 --rootfs /var/lib/containers/fedora --args bash
317
321 You can use SELinux to add security to the container. You must specify
322 the process label to run the init process inside of the container using
323 the --selinux-label.
324 # ocitools generate --bind /var/db:/data1 --selinux-label
327 system_u:system_r:svirt_lxc_net_t:s0:c1,c2 --rootfs
328 /var/lib/containers/fedora --args bash
329 Not in the above example we used a type of svirt_lxc_net_t and an MCS
332 Label of s0:c1,c2. If you want to guarantee separation between
333 containers, you need to make sure that each container gets launched
334 with a different MCS Label pair.
335 Also the underlying rootfs must be labeled with a matching label. For
338 the example above, you would execute a command like:
339 # chcon -R system_u:object_r:svirt_sandbox_file_t:s0:c1,c2
342 /var/lib/containers/fedora
343 This will set up the labeling of the rootfs so that the process
346 launched would be able to write to the container. If you wanted to
347 only allow it to read/execute the content in rootfs, you could execute:
348 # chcon -R system_u:object_r:usr_t:s0 /var/lib/containers/fedora
351 When using SELinux, be aware that the host has no knowledge of
354 container SELinux policy. Therefore, in the above example, if SELinux
355 policy is enforced, the /var/db directory is not writable to the
356 container. A "Permission Denied" message will occur and an avc: message
357 in the host's syslog.
358 To work around this, the following command needs to be generate in
361 order for the proper SELinux policy type label to be attached to the
362 host directory:
363 # chcon -Rt svirt_sandbox_file_t -l s0:c1,c2 /var/db
366 Now, writing to the /data1 volume in the container will be allowed and
370 the changes will also be reflected on the host in /var/db.
371
375 runc(1), ocitools(1)
376
380 April 2016, Originally compiled by Dan Walsh (dwalsh at redhat dot com)
381OCI Community OCI User Manuals OCI(1)