Stability	provisional
Portability	non-portable (requires Linux)
Safe Haskell	None
Language	Haskell2010

System.Linux.Namespaces

Contents

Main types and functions
Utility functions
User/Group mappings
Example

Description

This module provides bindings to the unshare(2) and setns(2) linux system calls. These functions can be used to create new namespaces by detaching the current process from its current namespaces, or to move the current process to an already existing namespace. Note that linux also provides the clone(2) function which can be used to create new namespaces, but we do not support this function in this module; the way this function works makes it hard to use it from haskell as it interacts badly with GHC'c RTS.

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 also problematic.

Synopsis

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 much, the function will fail. Use `Nothing` to allow any type.
-> IO ()

Move 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 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 :: Maybe ProcessID -> 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. `Nothing` means use the current process.
-> [UserMapping]
-> 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. `Nothing` means use the current process.
-> [GroupMapping]
-> 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"