Docker from Scratch workshop

linux

The linux module is a simple Python c extension, containing syscall wrappers missing from the Python os module. You will need to use these system calls to implement different aspect of process containment during the workshop.

linux.clone()
linux.clone(callback, flags, callback_args)

create a child process

Parameters:

  • callback (Callable) – python function to be executed by the forked child

  • flags (int) – combination (using |) of flags specifying what should be shared between the calling process and the child process. See below.

  • callback_args (tuple) – tuple of arguments for the callback function

Returns:

On success, the thread ID of the child process

Raises:

RuntimeError – if clone fails

Useful flags:

  • linux.CLONE_NEWNS - Unshare the mount namespace

  • linux.CLONE_NEWUTS - Unshare the UTS namespace (hostname, domainname, etc)

  • linux.CLONE_NEWNET - Unshare the network namespace

  • linux.CLONE_NEWPID - Unshare the PID namespace

linux.mount()
linux.mount(source, target, filesystemtype, mountflags, mountopts)

mount filesystem

Parameters:

  • source (str) – filesystem to attach (can be None)

  • target (str) – directory being attached to, or manipulated (in case of flag change)

  • filesystemtype (str) – filesystem supported by the kernel (can be None)

  • mountflags (int) – any combination (using |) of mount flags supported by mount(2). For the workshop you are most likely to use 0 (i.e. no flags), or a combination of: linux.MS_REC, linux.MS_PRIVATE

  • mountopts (str) – options passed to the specified filesystem (can be None)

Returns:

None

Raises:

RuntimeError – if mount fails

linux.pivot_root()
linux.pivot_root(new_root, put_old)

change the root filesystem

Parameters:

  • new_root (str) – New root file system

  • put_old (str) – Directory to move the current process root file system to

Returns:

None

Raises:

RuntimeError – if pivot_root fails

NOTE: The following restrictions apply to new_root and put_old:

  • They must be directories.

  • new_root and put_old must not be on the same filesystem as the current root.

  • new_root must be a mountpoint.

  • put_old must be underneath new_root, that is, adding a nonzero number of /.. to the string pointed to by put_old must yield the same directory as new_root.

  • No other filesystem may be mounted on put_old.

linux.sethostname()
linux.sethostname(hostname)

set the system hostname

Parameters:

hostname (str) – new hostname value

Returns:

None

Raises:

RuntimeError – if sethostname fails

linux.setns()
linux.setns(fd, nstype)

reassociate process with a namespace

Parameters:

  • fd (int) – file descriptor referring to a namespace to associate with

  • nstype (int) – one of the following: 0 (Allow any type of namespace to be joined), CLONE_NEWIPC (join IPC namespace), CLONE_NEWNET (join network namespace), or CLONE_NEWUTS (join UTS namespace)

Returns:

None

Raises:

RuntimeError – if setns fails

linux.umount()
linux.umount(target)

unmount filesystem

Parameters:

target (str) – the (topmost) filesystem this directory is mounted on will be removed

Returns:

None

Raises:

RuntimeError – if umount fails

linux.umount2()
linux.umount2(target, flags)

unmount filesystem but allows additional flags controlling the behavior of the operation

Parameters:

  • target (str) – the (topmost) filesystem this directory is mounted on will be removed

  • flags (int) – control the behavior of the operation. You can combine multiple flags using |. For the workshop you are most likely to use linux.MNT_DETACH

Returns:

None

Raises:

RuntimeError – if umount2 fails

linux.unshare()
linux.unshare(flags)

disassociate parts of the process execution context

Parameters:

flags (int) – which parts of the execution context should be unshared. You can combine multiple flags using |. See below for flags you might want to use in this workshop

Returns:

None

Raises:

RuntimeError – if unshare fails

Useful flags:

  • linux.CLONE_NEWNS - Unshare the mount namespace

  • linux.CLONE_NEWUTS - Unshare the UTS namespace (hostname, domainname, etc)

  • linux.CLONE_NEWNET - Unshare the network namespace

  • linux.CLONE_NEWPID - Unshare the PID namespace