sortix--sortix/subsystem/man

NAME:
subsystem - Creates a new instance of an operating system running under the current kernel under a specified root filesystem

SYNOPSIS:
subsystem [--max-memory=<max-memory-amount>[<max-memory-unit>]] [--nice=<nice-offset>] [--access=<access-devices> [--no-access=<no-access-devices>]] [--inherit=<devices> [--no-inherit=<devices>]] [--boot] <path-to-root-dir> [<init-cmd>]

DESCRIPTION:
Each process under the Sortix kernel belongs to an operating system. An operating system is an abstract object that consists of a filesystem containing programs and configuration, an amount of resources (RAM and CPU) available for use, and an account system that handles permissions and ownership. The Sortix kernel is able to run multiple operating systems (possibly even nested) at the same time. The program subsystem is able to create a new instance of an operating system. It runs in two modes depending on the presence of the --boot flag:

COMMAND LINE ARGUMENTS:
If <init-cmd> is not specified, then the program will default to /bin/init. Any standard IO to this program will be sent to the first process, and any standard IO from the first process echoed by this program.

If --boot is not specified, then a new operating system is created where <path-to-root-dir> is the new root directory, and where <init-cmd> is run as the first program, which will be running as the a copy of the current user.

If --boot is specified, and the current user owns the filesystem of <path-to-root-dir>, then a new operating system is created where <path-to-root-dir> is the new root directory, and where <init-cmd> is run as the first program, which will be running as the root user (in the new operating system's account system).


If --access=<access-devices> is specified, then the new OS will only have access to <access-devices> and no other devices. Specifying --access=all is equivalent to specifying all accessable devices (e.g. usable/mounted). If --access is not specified, then the program will default to --access=all.

If --no-access=<no-access-devices> is specified, then, if present, all devices in <no-access-devices> will be removed from --access=<access-devices>.


If --inherit=<inherit-devices> is specified, then the new user will gain ownership of <inherit-devices>, which will be removed from the current user and returned when the new subsystem is terminated. Specifying --inherit=all is equivalent to specifying all devices the current user owns. If --inherit is not specified, then the new user will not inherit any ownership from the current user.

If --no-inherit=<no-inherit-devices> is specified, then, if present, all devices in <no-inherit-devices> will be removed from --inherit=<inherit-devices>.

If --nice=<nice-offset> is specified, then all programs in new system will have the lowest possible niceness of <nice-offset> plus the lowest possible niceness of the current user.

If --max-memory=<max-memory-amount>[<max-memory-unit>] is specified, then the new system cannot allocate more than <max-memory-bytes> <max-memory-unit> of memory. <max-memory-unit> is the unit, e.g. 'B' (bytes), 'KiB' (kibibytes = 1024 bytes), 'MiB' (mibibytes = 1024 kibibytes), etc. If <max-memory-unit> is not specified, then <max-memory-unit> is assumed to be 'B' (bytes).

EXAMPLES:
An user booting a filesystem system he owns:
$ subsystem --boot /home/myuser/myfs /bin/init

An user chrooting a filesystem system as himself:
$ subsystem /home/myuser/newroot /bin/bash

To specify which devices the subsystem inherits ownership of:
$ subsystem --inherit=/dev/sdb1,/dev/sdb4 --boot /mnt/newos /bin/init

To let the subsystem inherit all ownership:
$ subsystem --inherit=all --boot /mnt/newos /bin/init

To let the subsystem inherit ownership of all but some devices:
$ subsystem --inherit=all --no-inherit=/dev/sdb1,/dev/sdb4 --boot /mnt/newos /bin/init

To specify which devices the subsystem can access:
$ subsystem --access=/dev/eth0,/dev/wlan1 --boot /mnt/newos /bin/init

To let the subsystem access everything (default):
$ subsystem --access=all --boot /mnt/newos /bin/init

To let the subsystem access everything but some devices:
$ subsystem --access=all --no-access=/dev/eth0 --boot /mnt/newos /bin/init

To set the memory allocation limit for an subsystem that compiles some program.
$ subsystem --max-memory=256MiB /home/myuser/myprefix /bin/gcc /sources/foo.c -o /bin/foo

To set some additional niceness while running a makefile in a subsystem:
$ subsystem --nice=20 /home/myuser/myprefix /usr/bin/make -f /sources/Makefile

The sortix initfs boot script would run something like this:
$ <some command that mounts the root fs at /fs>
$ subsystem --inherit=all --boot /fs