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()
orBaseNamespace.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:
- 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.
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.
Unshare multiple namespaces indicated by the boolean arguments.