io.systemd.NamespaceResource¶
Allocate transient UID ranges for user namespace, and assign mounts, cgroups and networking devices to them
| Property | Value |
|---|---|
| Go package | github.com/rossedman/sdvarlink/systemd/latest/namespaceresource |
| Socket | /run/systemd/io.systemd.NamespaceResource |
| Available since | systemd v257 |
| Methods · types · errors | 5 · 1 · 11 |
Methods¶
AllocateUserRange¶
passes file descriptors
Assigns a UID range to a client-allocated user namespace that has no UID range assigned so far, and registers it for assignment of other resources.
func (c *Client) AllocateUserRange(ctx context.Context, in AllocateUserRangeIn) (*AllocateUserRangeOut, error)
Parameters
| Field | Type | Description |
|---|---|---|
name |
string |
The name for the user namespace, a short string that must be fit to be included in a file name and in a user name. This name is included in the user records announced via NSS and is otherwise useful for debugging. |
mangleName |
?bool |
Controls whether to mangle the provided name if needed so that it is suitable for naming a user namespace. If true this will shorten the name as necessary or randomize it if that's not sufficient. If null defaults to false. |
size |
int |
The number of UIDs to assign. Must be 1 or 65536. If type is 'self', must be 1. |
target |
?int |
The target UID inside the user namespace. If not specified defaults to 0. If type is 'self', must be 0 or unset in which case the peer UID is mapped to itself. |
userNamespaceFileDescriptor |
int |
A file descriptor to an allocated userns with no current UID range assignments |
type |
?AllocateUserRangeType |
The type of allocation to perform. If 'managed' (the default), a transient UID/GID range is allocated from the dynamic range pool. If 'self', the peer UID/GID is mapped to itself. Defaults to 'managed'. |
delegateContainerRanges |
?int |
Number of transient 64K container UID/GID ranges to delegate. These are mapped 1:1 into the user namespace and can be used by nested user namespaces for container workloads. Must be between 0 and 16. Defaults to 0. |
mapForeign |
?bool |
If true, map the foreign UID range 1:1 into the user namespace. |
Reply
| Field | Type | Description |
|---|---|---|
name |
?string |
The name assigned to the user namespace. (This is particularly interesting in case mangleName was enabled). |
RegisterUserNamespace¶
passes file descriptors
Registers an already initialized user namespace for assignment of resources.
func (c *Client) RegisterUserNamespace(ctx context.Context, in RegisterUserNamespaceIn) (*RegisterUserNamespaceOut, error)
Parameters
| Field | Type | Description |
|---|---|---|
name |
string |
The name for the user namespace, a short string that must be fit to be included in a file name and in a user name, as in AllocateUserRange(). |
mangleName |
?bool |
Controls whether to mangle the provided name if needed so that it is suitable for naming a user namespace, as in AllocateUserRange() |
userNamespaceFileDescriptor |
int |
A user namespace file descriptor that is fully initialized |
Reply
| Field | Type | Description |
|---|---|---|
name |
?string |
The name assigned to the user namespace |
AddMountToUserNamespace¶
passes file descriptors
Adds a mount to a user namespace previously allocated or registered via AllocateUserRange() or RegisterUserNamespace(). This allowlists the mount for access by the user namespace.
Parameters
| Field | Type | Description |
|---|---|---|
userNamespaceFileDescriptor |
int |
A user namespace file descriptor previously allocated via AllocateUserRange() or registered via RegisterUserNamespace(). |
mountFileDescriptor |
int |
A mount file descriptor for the mount to allowlist for the specified user namespace. |
AddControlGroupToUserNamespace¶
passes file descriptors
Adds a cgroup to a user namespace previously allocated or registered via AllocateUserRange() or RegisterUserNamespace(). This passes ownership of the referenced cgroup to the user namespace's root user, and ensures the cgroup gets deleted when the user namespace is released.
func (c *Client) AddControlGroupToUserNamespace(ctx context.Context, in AddControlGroupToUserNamespaceIn) error
Parameters
| Field | Type | Description |
|---|---|---|
userNamespaceFileDescriptor |
int |
A user namespace file descriptor previously allocated via AllocateUserRange() or registered via RegisterUserNamespace(). |
controlGroupFileDescriptor |
int |
A file descriptor referencing a cgroup to assign to the root user of the specified user namespace. |
AddNetworkToUserNamespace¶
passes file descriptors
Adds a network interface to a user namespace previously allocated or registered via AllocateUserRange() or RegisterUserNamespace(). This creates a 'veth' or 'tap' device that is assigned to the user namespace, or owned by its root user.
func (c *Client) AddNetworkToUserNamespace(ctx context.Context, in AddNetworkToUserNamespaceIn) (*AddNetworkToUserNamespaceOut, error)
Parameters
| Field | Type | Description |
|---|---|---|
userNamespaceFileDescriptor |
int |
A user namespace file descriptor previously allocated via AllocateUserRange() or registered via RegisterUserNamespace(). |
networkNamespaceFileDescriptor |
?int |
A network namespace file descriptor to assign the network interface to. Only applies to network interfaces of type 'veth'. |
namespaceInterfaceName |
?string |
The network interface name to use for the network interface inside the network namespace. Only applies to network interfaces of type 'veth'. |
mode |
string |
The networking mode, one of 'veth' or 'tap'. If the former is selected a virtual Ethernet link between host and namespace is created. If the latter is selected an Ethernet Tap link is created and a file descriptor is returned for the namespace side. |
Reply
| Field | Type | Description |
|---|---|---|
hostInterfaceName |
string |
The chosen network interface name for the host side of the network. |
namespaceInterfaceName |
?string |
The chosen network interface name for the namespace side of the network. Only applies to network interfaces of type 'veth'. |
interfaceFileDescriptor |
?int |
The file descriptor for the namespace side of the network. Only applies to network interfaces of type 'tap'. |
Types¶
AllocateUserRangeType¶
The type of user range allocation to perform.
| Value | Description |
|---|---|
managed |
Allocate a transient UID/GID range from the dynamic range pool. This is the default. |
self |
Create a user namespace that maps the peer UID/GID to itself instead of allocating a transient UID range. |
Errors¶
| Error | Go type | Description |
|---|---|---|
UserNamespaceInterfaceNotSupported |
UserNamespaceInterfaceNotSupportedError |
User namespace delegation via io.systemd.NamespaceResource is not supported. |
NameExists |
NameExistsError |
A user namespace under the specified name exists already. |
UserNamespaceExists |
UserNamespaceExistsError |
The specified user namespace has been registered before. |
DynamicRangeUnavailable |
DynamicRangeUnavailableError |
The dynamic UID range is exhausted already. |
NoDynamicRange |
NoDynamicRangeError |
The dynamic UID range is not available on this system. |
UserNamespaceNotRegistered |
UserNamespaceNotRegisteredError |
The specified user namespace has not been registered. |
UserNamespaceWithoutUserRange |
UserNamespaceWithoutUserRangeError |
The specified user namespace has no UID range assigned. |
TooManyControlGroups |
TooManyControlGroupsError |
The per-user namespace limit of cgroups has been reached. |
ControlGroupAlreadyAdded |
ControlGroupAlreadyAddedError |
The specified cgroup has already been added to the user namespace. |
TooManyNetworkInterfaces |
TooManyNetworkInterfacesError |
The per-user namespace limit of network interfaces has been reached. |
TooManyDelegations |
TooManyDelegationsError |
The specified number of delegations exceeds the maximum allowed. |