Namespaces

Namespace is an isolation mechanism. In total there are 7 different namespace types each representing a certain operating system domain.

For example, MountNamespace allows to creating new mount points without affecting other processes.

Namespace classes should not be initialized directly. Instead either BaseNamespace.from_pid() or BaseNamespace.from_self() class methods should be used to create a namespace object which represents a reference to an existing namespace.

An existing namespace can be entered using BaseNamespace.setns(). A new namespace can be created using BaseNamespace.unshare() class method or unshare_namespaces() function.

File descriptors are a limited resource and every namespace reference requires one. Because of this a warning will be emitted if a namespace object was deallocated without closing the file descriptor. To avoid this use BaseNamespace.close() or a with block. For example:

from lxns.namespaces import UserNamespace

with UserNamespace.from_pid(123456) as user_ns:
    user_ns.setns()

# Inside the user namespace

Namespace object cannot be used after it was closed and all methods will raise ValueError.

All namespace classes implement similar API and only differ in the type of namespace they reference. For brevity only BaseNamespace has the methods documented.

class lxns.namespaces.BaseNamespace(fd: int, closefd: bool = True)

Base namespace class for all namespaces.

Should not be used directly.

__init__(fd: int, closefd: bool = True)

Wrap existing file descriptor in a Namespace object.

It is recommended to use the BaseNamespace.from_pid() or BaseNamespace.from_pid() methods over manually opening the namespace files.

Parameters:

• fd (int) – File descriptor that references the namespace.

• closefd (bool) – Close underlying file descriptor or not.

close() → None

Close namespace file descriptor.

Can be called multiple times in which case only first call will close the namespace and subsequent calls will be ignored.

fileno() → int

Return namespace underlying file descriptor.

Raises:

ValueError – Namespace was already closed.

classmethod from_pid(pid: int | Literal['self']) → Self

Open namespace from a process id.

classmethod from_self() → Self

Open caller current namespace.

classmethod get_current_limit() → int

Get the current limit for this type of namespace.

The limits are unique per user namespace and are propagated to the child namespaces.

classmethod get_current_ns_id() → int

Return the current namespace of this type unique identifier.

This is a class method that works without opening a namespace file.

get_user_namespace() → UserNamespace

Open user namespace that owns this namespace.

Returns:

User namespace.

Return type:

UserNamespace

property ns_id: int

Return the namespace unique identifier.

classmethod set_current_limit(new_limit: int) → None

Set the current limit for this type of namespace.

The limits are unique per user namespace and are propagated to the child namespaces.

setns() → None

Enter namespace.

Raises:

OSError – Errors returned by the syscall.

classmethod unshare() → None

Create and switch to the new namespace of this type.

class lxns.namespaces.UserNamespace(fd: int, closefd: bool = True)

User namespace.

Implements same API as BaseNamespace.

class lxns.namespaces.MountNamespace(fd: int, closefd: bool = True)

Mount namespace.

Implements same API as BaseNamespace.

class lxns.namespaces.NetworkNamespace(fd: int, closefd: bool = True)

Network namespace.

Implements same API as BaseNamespace.

class lxns.namespaces.IpcNamespace(fd: int, closefd: bool = True)

IPC namespace.

Implements same API as BaseNamespace.

class lxns.namespaces.CgroupNamespace(fd: int, closefd: bool = True)

Cgroups namespace.

Implements same API as BaseNamespace.

class lxns.namespaces.PidNamespace(fd: int, closefd: bool = True)

PID namespace.

Implements same API as BaseNamespace.

class lxns.namespaces.TimeNamespace(fd: int, closefd: bool = True)

Time namespace.

Implements same API as BaseNamespace.

class lxns.namespaces.UtsNamespace(fd: int, closefd: bool = True)

UTS namespace.

Provides isolation of system identifiers: hostname and NIS domain name.

Implements same API as BaseNamespace.

lxns.namespaces.ALL_NAMESPACE_CLASSES

All Namespace classes arranged in order suited for joining.

lxns.namespaces.unshare_namespaces(*, cgroup: bool = False, ipc: bool = False, network: bool = False, mount: bool = False, pid: bool = False, time: bool = False, user: bool = False, uts: bool = False) → None

Unshare multiple namespaces indicated by the boolean arguments.