System.Linux.Namespaces

This module provides bindings to the unshare(2) and setns(2) linux system calls. The former can be used to create new namespaces and move the calling process to them, whereas the latter can be used to move the calling process to an already existing namespace created by some other process.

Note that linux provides another function related to namespaces which is not supported by this module: clone(2). This function works like fork(2) and is used to create new namespaces (like unshare(2)). Unfortunately, like fork(2), it does not interact well with GHC'c RTS which is why it has been omitted from this module.

Note: Using this module in a program that uses the threaded RTS does not make much sense. Namespaces are per process/thread and manipulating them in one thread will not affect the namespaces of the other threads of the same process. The threaded RTS makes it is hard to predict what OS thread will be used to run the haskell threads. Therefore, using this module in such applications will result in unpredictable behavior. Similarly, using this module in ghci is problematic too.

Main types and functions

data Namespace

Types of namespaces.

Constructors

IPC

Network

Mount

PID

User

UTS

Instances

Bounded Namespace

Methods

minBound :: Namespace

maxBound :: Namespace

Enum Namespace

Methods

succ :: Namespace -> Namespace

pred :: Namespace -> Namespace

toEnum :: Int -> Namespace

fromEnum :: Namespace -> Int

enumFrom :: Namespace -> [Namespace]

enumFromThen :: Namespace -> Namespace -> [Namespace]

enumFromTo :: Namespace -> Namespace -> [Namespace]

enumFromThenTo :: Namespace -> Namespace -> Namespace -> [Namespace]

Eq Namespace

Methods

(==) :: Namespace -> Namespace -> Bool

(/=) :: Namespace -> Namespace -> Bool

Read Namespace

Methods

readsPrec :: Int -> ReadS Namespace

readList :: ReadS [Namespace]

readPrec :: ReadPrec Namespace

readListPrec :: ReadPrec [Namespace]

Show Namespace

Methods

showsPrec :: Int -> Namespace -> ShowS

show :: Namespace -> String

showList :: [Namespace] -> ShowS

unshare :: [Namespace] -> IO ()

Detach the process from one or more namespaces and move it to new ones. See the man page of unshare(2) for more details.

setNamespace

Arguments

:: Fd

A file descriptor referring to a namespace file in a /proc/[pid]/ns/ directory.

-> Maybe Namespace

Specify the namespace type that the file descriptor must refer to. If the two types do not match, the function will fail. Use Nothing to allow any type.

-> IO ()

Move the process to an already existing namespace. See the man page of setns(2) for more details. See also enterNamespace for a slightly higher level version of this function.

Utility functions

enterNamespace

Arguments

:: ProcessID

The pid of any process in the target namespace.

-> Namespace

The type of the namespace.

-> IO ()

Move the process to an already existing namespace. This is a wrapper around setNamespace. This function requires /proc to be mounted.

data NamespaceID

A unique namespace id.

Instances

Enum NamespaceID

Methods

succ :: NamespaceID -> NamespaceID

pred :: NamespaceID -> NamespaceID

toEnum :: Int -> NamespaceID

fromEnum :: NamespaceID -> Int

enumFrom :: NamespaceID -> [NamespaceID]

enumFromThen :: NamespaceID -> NamespaceID -> [NamespaceID]

enumFromTo :: NamespaceID -> NamespaceID -> [NamespaceID]

enumFromThenTo :: NamespaceID -> NamespaceID -> NamespaceID -> [NamespaceID]

Eq NamespaceID

Methods

(==) :: NamespaceID -> NamespaceID -> Bool

(/=) :: NamespaceID -> NamespaceID -> Bool

Integral NamespaceID

Methods

quot :: NamespaceID -> NamespaceID -> NamespaceID

rem :: NamespaceID -> NamespaceID -> NamespaceID

div :: NamespaceID -> NamespaceID -> NamespaceID

mod :: NamespaceID -> NamespaceID -> NamespaceID

quotRem :: NamespaceID -> NamespaceID -> (NamespaceID, NamespaceID)

divMod :: NamespaceID -> NamespaceID -> (NamespaceID, NamespaceID)

toInteger :: NamespaceID -> Integer

Num NamespaceID

Methods

(+) :: NamespaceID -> NamespaceID -> NamespaceID

(-) :: NamespaceID -> NamespaceID -> NamespaceID

(*) :: NamespaceID -> NamespaceID -> NamespaceID

negate :: NamespaceID -> NamespaceID

abs :: NamespaceID -> NamespaceID

signum :: NamespaceID -> NamespaceID

fromInteger :: Integer -> NamespaceID

Ord NamespaceID

Methods

compare :: NamespaceID -> NamespaceID -> Ordering

(<) :: NamespaceID -> NamespaceID -> Bool

(<=) :: NamespaceID -> NamespaceID -> Bool

(>) :: NamespaceID -> NamespaceID -> Bool

(>=) :: NamespaceID -> NamespaceID -> Bool

max :: NamespaceID -> NamespaceID -> NamespaceID

min :: NamespaceID -> NamespaceID -> NamespaceID

Read NamespaceID

Methods

readsPrec :: Int -> ReadS NamespaceID

readList :: ReadS [NamespaceID]

readPrec :: ReadPrec NamespaceID

readListPrec :: ReadPrec [NamespaceID]

Real NamespaceID

Methods

toRational :: NamespaceID -> Rational

Show NamespaceID

Methods

showsPrec :: Int -> NamespaceID -> ShowS

show :: NamespaceID -> String

showList :: [NamespaceID] -> ShowS

getNamespaceID

Arguments

:: Maybe ProcessID

The pid of any process in the target namespace. Use Nothing for the namespace of the calling process.

-> Namespace

The type of the namespace.

-> IO NamespaceID

Retrieve the id of a Namespace. Useful for debugging. This function requires /proc to be mounted.

User/Group mappings

data UserMapping

A single user mapping, used with user namespaces. See user_namespaces(7) for more details.

Constructors

UserMapping UserID UserID Int

Instances

Eq UserMapping

Methods

(==) :: UserMapping -> UserMapping -> Bool

(/=) :: UserMapping -> UserMapping -> Bool

Read UserMapping

Methods

readsPrec :: Int -> ReadS UserMapping

readList :: ReadS [UserMapping]

readPrec :: ReadPrec UserMapping

readListPrec :: ReadPrec [UserMapping]

Show UserMapping

Methods

showsPrec :: Int -> UserMapping -> ShowS

show :: UserMapping -> String

showList :: [UserMapping] -> ShowS

data GroupMapping

A single group mapping, used with user namespaces. See user_namespaces(7) for more details.

Constructors

GroupMapping GroupID GroupID Int

Instances

Eq GroupMapping

Methods

(==) :: GroupMapping -> GroupMapping -> Bool

(/=) :: GroupMapping -> GroupMapping -> Bool

Read GroupMapping

Methods

readsPrec :: Int -> ReadS GroupMapping

readList :: ReadS [GroupMapping]

readPrec :: ReadPrec GroupMapping

readListPrec :: ReadPrec [GroupMapping]

Show GroupMapping

Methods

showsPrec :: Int -> GroupMapping -> ShowS

show :: GroupMapping -> String

showList :: [GroupMapping] -> ShowS

writeUserMappings

Arguments

:: Maybe ProcessID

The pid of any process in the target user namespace. Use Nothing for the namespace of the calling process.

-> [UserMapping]

The mappings.

-> IO ()

Define the user mappings for the specified user namespace. This function requires /proc to be mounted. See user_namespaces(7) for more details.

writeGroupMappings

Arguments

:: Maybe ProcessID

The pid of any process in the target user namespace. Use Nothing for the namespace of the calling process.

-> [GroupMapping]

The mappings.

-> Bool

Prevent processes in the child user namespace from calling setgroups. This is needed if the calling process does not have the CAP_SETGID capability in the parent namespace.

-> IO ()

Define the group mappings for the specified user namespace. This function requires /proc to be mounted. See user_namespaces(7) for more details.

Example

Here's an example of creating a new network namespace. We also create a user namespace. This allows us to execute the program as an unprivileged user.

import System.Process
import System.Posix.User
import System.Linux.Namespaces

main :: IO ()
main = do
    putStrLn "*** Network interfaces in the parent namespace ***"
    callCommand "ip addr"
    putStrLn ""

    -- find the uid, we must do that before unshare
    uid <- getEffectiveUserID

    unshare [User, Network]
    -- map current user to user 0 (i.e. root) inside the namespace
    writeUserMappings Nothing [UserMapping 0 uid 1]

    -- enable the loopback interface
    -- we can do that because we are root inside the namespace
    callCommand "ip link set dev lo up"

    putStrLn "*** Network interfaces in the new namespace ***"
    callCommand "ip addr"