1 # SPDX-License-Identifier: GPL-2.0-only
5 manual_title = System Manager's Manual
6 [supercommand micoforia]
14 In addition to global options which apply to all subcommands, each
15 subcommand has its own set of options. The usual "--" separator must
16 be used to separate global options from subcommand specific options.
19 synopsis = [global-options...] [--] [<subcommand> [subcommand-options...]]
22 [option general-options-section]
23 summary = General options
26 summary = print help and exit
28 [option detailed-help]
29 summary = print help, including all details, and exit
31 summary = print version and exit
35 summary = use alternative config file (default: ~/.micoforiarc)
37 arg_info = required_arg
40 Options may be given at the command line or in the configuration
41 file. As usual, if an option is given both at the command line and
42 in the configuration file, the command line option takes precedence.
44 The config file may contain global options as well as options for
45 any subcommand, but subcommand specific options must be placed in a
46 separate section. See the Examples section of the man page.
49 summary = control amount of logging
51 arg_info = required_arg
55 LSGLL_DEBUG = "debug",
57 LSGLL_NOTICE = "notice",
58 LSGLL_WARNING = "warning",
59 LSGLL_ERROR = "error",
65 Log only messages with severity greater or equal than the given
66 value. Possible values:
68 debug: produces really noisy output.
69 info: still noisy, but won't fill up the disk quickly.
70 notice: indicates normal, but significant event.
71 warning: unexpected events that can be handled.
72 error: unhandled error condition.
73 crit: system might be unreliable.
74 emerg: last message before exit.
77 [option general-options-section]
78 summary = Global Container Options
81 The options in this section apply to all containers. Most of them
82 have a per-container counterpart which can be specified to override
85 [option default-root-prefix]
86 summary = path to the parent directory of the container root file systems
88 arg_info = required_arg
90 default_val = /var/lib/micoforia
92 For containers which do not specify their own root directory the path
93 to the container root is derived from the argument of this option by
94 appending a slash and the container name.
97 summary = directory which contains the container log files
98 arg_info = required_arg
101 default_val = /var/log/micoforia
103 The log messages of each container are written to a dedicated
104 logfile. This option controls in which directroy these files are
105 written (start subcommand) or expected (log subcommand).
107 Nothing is written to the logfile if the container is started in
110 [option default-pre-start-hook]
111 summary = command to be executed before the container starts
113 arg_info = required_arg
117 This hook is run early during container startup. All veth device
118 pairs have been created, but no namespace or cgroup operations have
119 been performed at this point.
121 If the root file system of the container must be prepared, this is the
122 right place to perform this task. Unlike the pre exec hook described
123 below, this hook is only called once.
125 The following environment variables are set: MICOFORIA_CONTAINER_NAME,
126 MICOFORIA_IFSPECS, MICOFORIA_ROOT_DIR.
128 [option default-pre-exec-hook]
129 summary = command to be executed before /sbin/init is executed
131 arg_info = required_arg
135 This runs with all namespaces already unshared and cgroup settings
136 applied but before the root directory is switched to the container
137 root. The hostname has already been changed to the container name
138 and the network interfaces have been renamed to eth0, eth1, etc.
140 This is the right place to perform additional cgroup or namespace
141 operations. When the container is rebooted, the pre-exec is called
142 again, just before control is handed over to the new init process.
144 Only MICOFORIA_ROOT_DIR is set in this hook.
146 [option default-init]
147 summary = control the handover to the init process of the container
149 arg_info = required_arg
151 default_val = /sbin/init
153 This program is executed as the last step of the container startup
154 procedure as pid 1. At this point the root directory of the process
155 has already been changed, so the given argument refers to a path
156 relative to the container root directory.
158 [option default-bridge]
159 summary = ethernet bridge to use by default
162 arg_info = required_arg
164 default_val = micoforia
166 Applies to all containers which do not specify their own network
167 interface(s) with --net. If this is given multiple times, containers
168 will be equipped with multiple interfaces.
170 [option default-cgroup-dac]
171 summary = specify which device nodes containers may access/create by default
174 arg_info = required_arg
177 Applies to all containers which do not specify their own access
178 control lists. May be given multiple times. Each device access control
179 specifier must be of the form {allow|deny} <entry>, where <entry>
180 is a suitable device access control string for the devices.allow or
181 devices.deny file of the cgroup-v1 controller. Order matters.
183 If this option is not given, and the corresponding per-container
184 option is not given either, a reasonable default applies which allows
185 access to the most common character devices (/dev/zero, /dev/null,
186 /dev/urandom, etc.) but denies access to most other devices including
189 Example: allow c 1:5 rwm
191 [option default-cpu-cores]
192 summary = Number of cores to use by default (zero means unlimited)
194 arg_info = required_arg
198 The limit is enforced by the cpu cgroup-v2 controller. Note that in
199 contrast to the cpuset controller of cgroup-v1 this controller does not
200 restrict the container to a set of admissible CPUs. Instead, it limits
201 the number of CPU cycles per time unit for the processes in the cgroup.
203 [option default-memory-limit]
204 summary = Memory usage throttle limit (zero means no limit)
206 arg_info = required_arg
210 The value specified here is written to the cgroup-v2 memory.high
211 control file of all containers which do not specify their own limit.
213 [option default-io-max]
214 summary = I/O limit (zero means no limit)
217 arg_info = required_arg
220 The I/O specifier argument must be a valid string for the io.max file
221 of the cgroup-v2 controller. For example, the string "1:5 rbps=1024"
222 limits the read I/O rate for the /dev/zero device to 1K per second.
224 [option default-capdrop]
225 summary = Capabilities to drop by default
228 arg_info = required_arg
231 The capability specifier argument is the text representation of a
232 capability, like CAP_SYS_MODULE. All given capabilities will be dropped
233 from the bounding set of the container init process, hence from all
234 all processes of the container. If this option is not given, and no
235 per-container capabilities to drop are given either, CAP_SYS_MODULE,
236 CAP_SYS_TIME, and CAP_SYS_RESOURCE are dropped.
238 See capabilities(7) for the list of capabilities and their meaning.
241 summary = Minor number of a tty device to capture by default
244 arg_info = required_arg
247 Normally the container's init process starts at least one "getty"
248 login session on a tty port /dev/ttyX, where X is the minor device
249 ID. This option lets you capture these login sessions and forward them
250 to another micoforia process executing the "attach" subcommand. For
251 each time the option is given, the device with the given minor device
254 If this is not given, /dev/tty1 will be captured.
256 [option general-options-section]
257 summary = Per-Container Options
260 These override the global container options above. Most of them take
261 a compound argument of the form <name:value>, where the first part
262 is the name of the container to which the option should be applied.
264 Unless noted otherwise, if both a global option and the corresponding
265 per-container option is given, the per-container option takes
269 summary = name of the container
272 arg_info = required_arg
275 Used for the hostname, the name of the veth interfaces and the name of
276 the cgroup directory. The name may only contain characters of the set
277 [a-zA-Z0-9-] and the length must not exceed 32 characters.
279 This does not need to be given if one of the compound options below
282 [option pre-start-hook]
283 summary = See --default-pre-start-hook
285 typestr = name:command
286 arg_info = required_arg
288 [option pre-exec-hook]
289 summary = See --default-pre-exec-hook
291 typestr = name:command
292 arg_info = required_arg
295 summary = See --default-init
296 typestr = name:command
298 arg_info = required_arg
301 summary = Equip the container with a non-default network interface
303 typestr = name:ifspec
304 arg_info = required_arg
307 The interface specifier is of the form bridge[:hwaddr]. If no hardware
308 address is given, a random address will be used. See --default-bridge.
310 Unlike the other compound options of this section, this option is
311 cumulative in that multiple options with the same container name do
312 not override each other but accumulate, resulting in a container with
313 multiple network interfaces.
315 [option root-directory]
316 summary = Path to the container root directory. See --default-root-prefix.
319 arg_info = required_arg
324 summary = See --default-cgroup-dac
325 typestr = name:dacspec
327 arg_info = required_arg
330 summary = See --default-cpu-cores
333 arg_info = required_arg
335 [option memory-limit]
336 summary = See --default-memory-limit
337 typestr = name:gigabytes
339 arg_info = required_arg
342 summary = See --default-io-max
344 typestr = name:iospec
345 arg_info = required_arg
348 summary = See --default-capdrop
350 typestr = name:capspec
351 arg_info = required_arg
354 summary = See --default-tty
357 arg_info = required_arg
361 micoforia supports the subcommands described below. If no subcommand
362 is given, the list of available subcommands is shown and the program
363 terminates successfully without performing any further action.
367 purpose = start one or more containers
368 non-opts-name = [<name>...]
370 If no container is given, all configured containers are started.
374 summary = do not run as background daemon
376 Normally, the process detaches from the console and continues to run
377 in the background. When this option is given, only a single container
378 can be started, and this container will run with its /dev/console
379 device redirected to the local tty, making the container startup
380 messages visible on the local tty.
382 Moreover, stdin is forwarded to the first configured tty device
383 (/dev/tty1 by default) of the container, and anything received from
384 the other end of the forwarding is dumped to stdout. This allows for
385 logins on the "local" console of the container, provided the container
386 starts getty process which listens on the tty device.
389 purpose = shutdown one or more containers
390 non-opts-name = [<name>...]
392 This subcommand works by executing halt(8) in container context.
393 If no container is given, halt(8) is executed in all configured
398 summary = wait until all containers have terminated
400 Without --wait the micoforia process which executes the stop
401 subcommand exits after spawning one halt(8) process per container
402 to be stopped. If --wait is given, the subcommand waits until all
403 containers have terminated or the timeout expires. This is handy for
404 system shutdown scripts which are supposed to terminate all running
408 If --wait is not given, the subcommand exits successfully if and only
409 if all signals were sent successfully. With --wait the subcommand
410 exits successfully if, additionally, all signalled processes have
411 terminated before the timeout expires.
415 purpose = reboot containers
416 non-opts-name = [<name>...]
418 Containers are rebooted and killed by sending a signal to a micoforia
419 process which executes the start subcommand.
422 purpose = force containers to terminate
423 non-opts-name = [<name>...]
425 This works like the reboot subcommand, but a different signal is used
426 to notify the container.
430 summary = wait until all signalled containers have terminated
432 Without --wait the micoforia process which executes the kill subcommand
433 exits right after the underlying kill(2) system call returns. At this
434 point the signalled process might still be alive although SIGKILL
435 was sent. If --wait is given, the process waits until the signalled
436 processes have terminated or the timeout expires.
439 purpose = list containers
440 non-opts-name = [<name>...]
442 Several listing modes are available. By default, only the running
443 containers are listed. If no container name is given, all configured
444 containers are taken into account.
449 summary = Also list containers which are not running
452 summary = Do not print any output
454 For scripts to determine from the exit code whether all of the given
455 containers are running.
459 summary = Show also the pid, and the cpu and memory limits
461 This overrides --quiet. That is, if both --quiet and --long are given,
462 the long listing is shown,
466 summary = Show all container settings, one setting per line
468 This overrides --quiet and --long.
471 The subcommand exits successfully if and only if all given/configured
472 containers could be listed. Unless --all is given, it is considered
473 an error if a given container is not running. In particular, when ls
474 is executed with no arguments at all, it exits successfully if and
475 only if all configured containers are running.
478 purpose = print process list of one or more containers
479 non-opts-name = [<name>...]
481 This runs pstree(1). The container init process is always the third
482 process shown. Process IDs refer to the parent PID namespace, which
483 is why the process ID of the container init is not shown as 1.
487 summary = also show the two micoforia processes
489 purpose = map the console of a running container to the local terminal.
490 non-opts-name = [<name>...]
492 It is an error if stdin is not associated with a terminal device.
496 summary = terminal to connect
497 arg_info = required_arg
502 This operation can only succeed if the given tty is forwarded by the
503 container. See --tty and --default-tty.
507 summary = don't fail but steal the tty if it is already attached
509 purpose = list available subcommands or print subcommand-specific help
510 non-opts-name = [subcommand]
512 Without any arguments, help prints the list of available
513 subcommands. When called with a subcommand name argument, it prints
514 the help text of the given subcommand.
518 summary = show the long help text
520 If the optional argument is supplied, the long help text contains the
521 synopsis, the purpose and the description of the specified subcommand,
522 followed by the option list including summary and help text of each
523 option. Without --long, the short help is shown instead. This omits
524 the description of the subcommand and the option help.
526 If no subcommand is supplied but --long is given, the list contains the
527 purpose of each subcommand.
530 [subcommand configtest]
531 purpose = run a configuration file syntax test
533 This subcommand checks the command line options and the configuration
534 file for syntactic and semantic correctness. It either reports
535 "Syntax Ok" and exits successfully or prints information about the
536 first error and terminates with exit code 1.
540 purpose = edit the configuration file
542 The editor to start is derived from the EDITOR environment variable.
543 If this variable is not set, vi is assumed.
547 purpose = run a command in a container namespace
548 non-opts-name = <name> [<command> [arg...]]
550 This executes the nsenter(1) command to enter the namespaces of
551 the init process of the given container. If no command is given,
552 the login command is run to start a root shell.
556 purpose = show the log file for the given container
557 non-opts-name = [<name>]
559 This executes cat(1) or less(1), depending on whether or not stdin
560 and stdout are associated with a terminal device.
563 .SS The Cgroup File Systems
564 There are two implementations of Linux control groups called
568 Both come with their own pseudo filesystem.
570 requires both file systems to be mounted at
574 Version 1 cgroups are only used to enforce device access control for
575 the containers, so the cgroup-v1 pseudo filesystem should be mounted
576 with only this controller enabled. See the Examples section below
577 for how to do this. Future versions of
579 might switch to the devices controller of cgroup-v2.
581 The container name is used also for the name of the network device
582 and as a directory name if no explicit root directory is given with
583 --root-prefix. Therefore container names must not exceed 32 characters,
584 which must all be alphanumeric or '-'. In particular, whitespace and
585 underscore ('_') are not permitted.
590 Create a bash alias named
594 which activates debug messages and already includes the double dash
595 to separate global options from subcommand options:
599 .B alias m7a='micoforia --loglevel debug --'
603 Set up an ethernet bridge named
605 add the physical interface
607 to it and give the bridge interface an IP address:
611 .B brctl addbr micoforia
612 .B ip link set up micoforia
613 .B brctl addif micoforia eth1
614 .B ip a a 192.168.137.1/24 dev micoforia
618 Mount the two cgroup file systems, but only activate the
620 controller of cgroup-v1:
624 .B mkdir -p /var/cgroup && mount -t cgroup -o devices cgroup /var/cgroup
625 .B mkdir -p /var/cgroup2 && mount -t cgroup2 cgroup2 /var/cgroup2
631 to mount the cgroup file systems automatically at boot:
635 .B none /var/cgroup cgroup devices 0 0
636 .B none /var/cgroup2 cgroup2 defaults 0 0
640 Download a base Debian12 installation with all packages of priority
641 required and important, including apt:
645 .B debootstrap bookworm /var/lib/micoforia/debian12 http://deb.debian.org/debian/
649 The same for Ubuntu-22.04:
653 .B debootstrap jammy /var/lib/micoforia/ubuntu-22.04 http://de.archive.ubuntu.com/ubuntu
657 Set the root password of the container
662 .B chroot /var/lib/micoforia/c1 passwd
666 Start the container in foreground mode:
670 .B m7a start --foreground c1
674 Start the container in the backround and run a shell:
685 of the running container (type CTRL+a q to detach):
693 Ask the container to shut down, and wait for the shutdown procedure
698 .B m7a stop --wait c1
702 Check whether the container is running:
706 .B m7a ls --quiet c1 && echo yes || echo no
710 A simple config file:
714 .B # two global options
717 .B # an option for the "attach" subcommand
727 Copyright (C) COPYRIGHT_YEAR() AUTHOR()
731 This is free software: you are free to change and redistribute it.
733 There is NO WARRANTY, to the extent permitted by law.