attach_to_bridge(): Improve error message.
[micoforia.git] / micoforia.suite.m4
1 # SPDX-License-Identifier: GPL-2.0-only
2 [suite micoforia]
3 caption = Subcommands
4 mansect = 8
5 manual_title = System Manager's Manual
6 [supercommand micoforia]
7 [description]
8 DESCRIPTION1()
9
10 DESCRIPTION2()
11
12 DESCRIPTION3()
13
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.
17
18 [/description]
19 synopsis = [global-options...] [--] [<subcommand> [subcommand-options...]]
20 purpose = SLOGAN()
21
22 [option general-options-section]
23 summary = General options
24 flag ignored
25 [option help]
26 summary = print help and exit
27 short_opt = h
28 [option detailed-help]
29 summary = print help, including all details, and exit
30 [option version]
31 summary = print version and exit
32 short_opt = V
33 [option config-file]
34 short_opt = c
35 summary = use alternative config file (default: ~/.mismarc)
36 typestr = path
37 arg_info = required_arg
38 arg_type = string
39 [help]
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.
43
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.
47 [/help]
48 [option loglevel]
49 summary = control amount of logging
50 short_opt = l
51 arg_info = required_arg
52 arg_type = string
53 typestr = severity
54 values = {
55 LSGLL_DEBUG = "debug",
56 LSGLL_INFO = "info",
57 LSGLL_NOTICE = "notice",
58 LSGLL_WARNING = "warning",
59 LSGLL_ERROR = "error",
60 LSGLL_CRIT = "crit",
61 LSGLL_EMERG = "emerg"
62 }
63 default_val = warning
64 [help]
65 Log only messages with severity greater or equal than the given
66 value. Possible values:
67
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.
75 [/help]
76
77 [option general-options-section]
78 summary = Global Container Options
79 flag ignored
80 [help]
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
83 the global default.
84 [/help]
85 [option default-root-prefix]
86 summary = path to the parent directory of the container root file systems
87 typestr = directory
88 arg_info = required_arg
89 arg_type = string
90 default_val = /var/lib/micoforia
91 [help]
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.
95 [/help]
96 [option logdir]
97 summary = directory which contains the container log files
98 arg_info = required_arg
99 arg_type = string
100 typestr = directory
101 default_val = /var/log/micoforia
102 [help]
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).
106
107 Nothing is written to the logfile if the container is started in
108 foreground mode.
109 [/help]
110 [option default-pre-start-hook]
111 summary = command to be executed before the container starts
112 typestr = command
113 arg_info = required_arg
114 arg_type = string
115 default_val = true
116 [help]
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.
120
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.
124
125 The following environment variables are set: MICOFORIA_CONTAINER_NAME,
126 MICOFORIA_IFSPECS, MICOFORIA_ROOT_DIR.
127 [/help]
128 [option default-pre-exec-hook]
129 summary = command to be executed before /sbin/init is executed
130 typestr = command
131 arg_info = required_arg
132 arg_type = string
133 default_val = true
134 [help]
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.
139
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.
143
144 Only MICOFORIA_ROOT_DIR is set in this hook.
145 [/help]
146 [option default-init]
147 summary = control the handover to the init process of the container
148 typestr = command
149 arg_info = required_arg
150 arg_type = string
151 default_val = /sbin/init
152 [help]
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.
157 [/help]
158 [option default-bridge]
159 summary = ethernet bridge to use by default
160 typestr = bridge
161 flag multiple
162 arg_info = required_arg
163 arg_type = string
164 default_val = micoforia
165 [help]
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.
169 [/help]
170 [option default-cgroup-dac]
171 summary = specify which device nodes containers may access/create by default
172 typestr = dacspec
173 flag multiple
174 arg_info = required_arg
175 arg_type = string
176 [help]
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.
182
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
187 all block devices.
188
189 Example: allow c 1:5 rwm
190 [/help]
191 [option default-cpu-cores]
192 summary = Number of cores to use by default (zero means unlimited)
193 typestr = num
194 arg_info = required_arg
195 arg_type = uint32
196 default_val = 0
197 [help]
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.
202 [/help]
203 [option default-memory-limit]
204 summary = Memory usage throttle limit (zero means no limit)
205 typestr = gigabytes
206 arg_info = required_arg
207 arg_type = uint32
208 default_val = 0
209 [help]
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.
212 [/help]
213 [option default-io-max]
214 summary = I/O limit (zero means no limit)
215 flag multiple
216 typestr = iospec
217 arg_info = required_arg
218 arg_type = string
219 [help]
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.
223 [/help]
224 [option default-capdrop]
225 summary = Capabilities to drop by default
226 typestr = capspec
227 flag multiple
228 arg_info = required_arg
229 arg_type = string
230 [help]
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.
237
238 See capabilities(7) for the list of capabilities and their meaning.
239 [/help]
240 [option default-tty]
241 summary = Minor number of a tty device to capture by default
242 typestr = minor
243 flag multiple
244 arg_info = required_arg
245 arg_type = uint32
246 [help]
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
252 number is captured.
253
254 If this is not given, /dev/tty1 will be captured.
255 [/help]
256 [option general-options-section]
257 summary = Per-Container Options
258 flag ignored
259 [help]
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.
263
264 Unless noted otherwise, if both a global option and the corresponding
265 per-container option is given, the per-container option takes
266 precedence.
267 [/help]
268 [option container]
269 summary = name of the container
270 flag multiple
271 typestr = name
272 arg_info = required_arg
273 arg_type = string
274 [help]
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.
278
279 This does not need to be given if one of the compound options below
280 are given instead.
281 [/help]
282 [option pre-start-hook]
283 summary = See --default-pre-start-hook
284 flag multiple
285 typestr = name:command
286 arg_info = required_arg
287 arg_type = string
288 [option pre-exec-hook]
289 summary = See --default-pre-exec-hook
290 flag multiple
291 typestr = name:command
292 arg_info = required_arg
293 arg_type = string
294 [option init]
295 summary = See --default-init
296 typestr = name:command
297 flag multiple
298 arg_info = required_arg
299 arg_type = string
300 [option net]
301 summary = Equip the container with a non-default network interface
302 flag multiple
303 typestr = name:ifspec
304 arg_info = required_arg
305 arg_type = string
306 [help]
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.
309
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.
314 [/help]
315 [option root-directory]
316 summary = Path to the container root directory. See --default-root-prefix.
317 flag multiple
318 typestr = name:path
319 arg_info = required_arg
320 arg_type = string
321 [help]
322 [/help]
323 [option cgroup-dac]
324 summary = See --default-cgroup-dac
325 typestr = name:dacspec
326 flag multiple
327 arg_info = required_arg
328 arg_type = string
329 [option cpu-cores]
330 summary = See --default-cpu-cores
331 typestr = name:num
332 flag multiple
333 arg_info = required_arg
334 arg_type = string
335 [option memory-limit]
336 summary = See --default-memory-limit
337 typestr = name:gigabytes
338 flag multiple
339 arg_info = required_arg
340 arg_type = string
341 [option io-max]
342 summary = See --default-io-max
343 flag multiple
344 typestr = name:iospec
345 arg_info = required_arg
346 arg_type = string
347 [option capdrop]
348 summary = See --default-capdrop
349 flag multiple
350 typestr = name:capspec
351 arg_info = required_arg
352 arg_type = string
353 [option tty]
354 summary = See --default-tty
355 typestr = name:minor
356 flag multiple
357 arg_info = required_arg
358 arg_type = string
359
360 [introduction]
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.
364 [/introduction]
365
366 [subcommand start]
367 purpose = start one or more containers
368 non-opts-name = [<name>...]
369 [description]
370 If no container is given, all configured containers are started.
371 [/description]
372 [option foreground]
373 short_opt = F
374 summary = do not run as background daemon
375 [help]
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.
381
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.
387 [/help]
388 [subcommand stop]
389 purpose = shutdown one or more containers
390 non-opts-name = [<name>...]
391 [description]
392 This subcommand works by executing halt(8) in container context.
393 If no container is given, halt(8) is executed in all configured
394 container contexts.
395 [/description]
396 [option wait]
397 short_opt = w
398 summary = wait until all containers have terminated
399 [help]
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
405 containers.
406 [/help]
407 [closing]
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.
412 [/closing]
413
414 [subcommand reboot]
415 purpose = reboot containers
416 non-opts-name = [<name>...]
417 [description]
418 Containers are rebooted and killed by sending a signal to a micoforia
419 process which executes the start subcommand.
420 [/description]
421 [subcommand kill]
422 purpose = force containers to terminate
423 non-opts-name = [<name>...]
424 [description]
425 This works like the reboot subcommand, but a different signal is used
426 to notify the container.
427 [/description]
428 [option wait]
429 short_opt = w
430 summary = wait until all signalled containers have terminated
431 [help]
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.
437 [/help]
438 [subcommand ls]
439 purpose = list containers
440 non-opts-name = [<name>...]
441 [description]
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.
445
446 [/description]
447 [option all]
448 short_opt = a
449 summary = Also list containers which are not running
450 [option quiet]
451 short_opt = q
452 summary = Do not print any output
453 [help]
454 For scripts to determine from the exit code whether all of the given
455 containers are running.
456 [/help]
457 [option long]
458 short_opt = l
459 summary = Show also the pid, and the cpu and memory limits
460 [help]
461 This overrides --quiet. That is, if both --quiet and --long are given,
462 the long listing is shown,
463 [/help]
464 [option verbose]
465 short_opt = v
466 summary = Show all container settings, one setting per line
467 [help]
468 This overrides --quiet and --long.
469 [/help]
470 [closing]
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.
476 [/closing]
477 [subcommand ps]
478 purpose = print process list of one or more containers
479 non-opts-name = [<name>...]
480 [description]
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.
484 [/description]
485 [option all]
486 short_opt = a
487 summary = also show the two micoforia processes
488 [subcommand attach]
489 purpose = map the console of a running container to the local terminal.
490 non-opts-name = [<name>...]
491 [description]
492 It is an error if stdin is not associated with a terminal device.
493 [/description]
494 [option tty]
495 short_opt = t
496 summary = terminal to connect
497 arg_info = required_arg
498 arg_type = uint32
499 typestr = minor
500 default_val = 1
501 [help]
502 This operation can only succeed if the given tty is forwarded by the
503 container. See --tty and --default-tty.
504 [/help]
505 [option force]
506 short_opt = f
507 summary = don't fail but steal the tty if it is already attached
508 [subcommand help]
509 purpose = list available subcommands or print subcommand-specific help
510 non-opts-name = [subcommand]
511 [description]
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.
515 [/description]
516 [option long]
517 short_opt = l
518 summary = show the long help text
519 [help]
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.
525
526 If no subcommand is supplied but --long is given, the list contains the
527 purpose of each subcommand.
528 [/help]
529
530 [subcommand configtest]
531 purpose = run a configuration file syntax test
532 [description]
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.
537 [/description]
538
539 [subcommand edit]
540 purpose = edit the configuration file
541 [description]
542 The editor to start is derived from the EDITOR environment variable.
543 If this variable is not set, vi is assumed.
544 [/description]
545
546 [subcommand enter]
547 purpose = run a command in a container namespace
548 non-opts-name = <name> [<command> [arg...]]
549 [description]
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.
553 [/description]
554
555 [subcommand log]
556 purpose = show the log file for the given container
557 non-opts-name = [<name>]
558 [description]
559 This executes cat(1) or less(1), depending on whether or not stdin
560 and stdout are associated with a terminal device.
561 [/description]
562 [section Notes]
563 .SS The Cgroup File Systems
564 There are two implementations of Linux control groups called
565 .I cgroup-v1
566 and
567 .IR cgroup-v2 .
568 Both come with their own pseudo filesystem.
569 .B micoforia
570 requires both file systems to be mounted at
571 .IR /var/cgroup
572 and
573 .IR /var/cgroup2 .
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
578 .B micoforia
579 might switch to the devices controller of cgroup-v2.
580 .SS Container Names
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.
586
587 [/section]
588 [section Examples]
589 .IP \(bu 2
590 Create a bash alias named
591 .I m7a
592 for
593 .I micoforia
594 which activates debug messages and already includes the double dash
595 to separate global options from subcommand options:
596
597 .RS 6
598 .EX
599 .B alias m7a='micoforia --loglevel debug --'
600 .EE
601 .RE
602 .IP \(bu 2
603 Set up an ethernet bridge named
604 .IR micoforia ,
605 add the physical interface
606 .I eth1
607 to it and give the bridge interface an IP address:
608
609 .RS 6
610 .EX
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
615 .EE
616 .RE
617 .IP \(bu 2
618 Mount the two cgroup file systems, but only activate the
619 .I devices
620 controller of cgroup-v1:
621
622 .RS 6
623 .EX
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
626 .EE
627 .RE
628 .IP \(bu 2
629 Entries for
630 .I /etc/fstab
631 to mount the cgroup file systems automatically at boot:
632
633 .RS 6
634 .EX
635 .B none /var/cgroup cgroup devices 0 0
636 .B none /var/cgroup2 cgroup2 defaults 0 0
637 .EE
638 .RE
639 .IP \(bu 2
640 Download a Debian10 root file system to
641 .IR /var/lib/micoforia/debian10 ,
642 set the root password and let micoforia set the hostname
643
644 .RS 6
645 .EX
646 .B debootstrap --variant=minbase buster /var/lib/micoforia/debian10 http://deb.debian.org/debian/
647 .B chroot /var/lib/micoforia/debian10 passwd
648 .B rm -f /var/lib/micoforia/debian10/etc/hostname
649 .EE
650 .RE
651 .IP \(bu 2
652 Download a minimal Ubuntu-18.04 root file system to
653 .IR /var/lib/micoforia/c1 ,
654 set the root password and configure the
655 .I eth0
656 interface, using a static IP address:
657
658 .RS 6
659 .EX
660 .B debootstrap --include openssh-server --include ifupdown bionic /var/lib/micoforia/c1 http://de.archive.ubuntu.com/ubuntu
661 .B chroot /var/lib/micoforia/c1 passwd
662 .B printf 'auto eth0\(rsniface eth0 inet static\(rsnaddress 192.168.137.2/24\(rsn' \
663 >> /var/lib/micoforia/c1/etc/network/interfaces
664 .B echo 'PermitRootLogin yes' >> /var/lib/micoforia/c1/etc/ssh/sshd_config
665 .EE
666 .RE
667 .IP \(bu 2
668 Start the container in foreground mode:
669
670 .RS 6
671 .EX
672 .B micoforia --container c1 --start --foreground
673 .EE
674 .RE
675 .IP \(bu 2
676 Attach to
677 .I tty1
678 of the running container:
679
680 .RS 6
681 .EX
682 .B m7a attach c1
683 .EE
684 .RE
685 .IP \(bu 2
686 Ask the container to shut down, and wait for the shutdown procedure
687 to complete:
688
689 .RS 6
690 .EX
691 .B m7a stop --wait c1
692 .EE
693 .RE
694 .IP \(bu 2
695 Check whether the container is running:
696
697 .RS 6
698 .EX
699 .B m7a ls --quiet c1 && echo yes || echo no
700 .EE
701 .RE
702 .IP \(bu 2
703 A simple config file:
704
705 .RS 6
706 .EX
707 .B # two global options
708 .B loglevel info
709 .B container c1
710 .B # an option for the "attach" subcommand
711 .B [start]
712 .B \ \ \ \ tty 2
713 .EE
714 .RE
715
716 [/section]
717 [section copyright]
718 Written by AUTHOR()
719 .br
720 Copyright (C) COPYRIGHT_YEAR() AUTHOR()
721 .br
722 License: LICENSE()
723 .br
724 This is free software: you are free to change and redistribute it.
725 .br
726 There is NO WARRANTY, to the extent permitted by law.
727 .P
728 Web page:
729 .UR URL()
730 .UE
731 .br
732 Git clone `URL':
733 .UR CLONE_URL()
734 .UE
735 .br
736 Gitweb:
737 .UR GITWEB_URL()
738 .UE
739 .br
740 Author's home page:
741 .UR HOME_URL()
742 .UE
743 .br
744 Report bugs to
745 .MT EMAIL()
746 AUTHOR()
747 .ME
748 [/section]
749 [section see also]
750 .BR lxc (7),
751 .BR brct l(8),
752 .BR ip (8)
753 .BR pstree (1)
754 [/section]