linux-namespaces-0.1.1.1: Create new or enter an existing linux namespaces

Stabilityprovisional
Portabilitynon-portable (requires Linux)
Safe HaskellNone
LanguageHaskell2010

System.Linux.Namespaces

Contents

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 Source

Types of namespaces.

Constructors

IPC 
Network 
Mount 
PID 
User 
UTS 

unshare :: [Namespace] -> IO () Source

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 Source

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 Source

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.

getNamespaceID :: Maybe ProcessID -> Namespace -> IO NamespaceID Source

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

User/Group mappings

data UserMapping Source

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

data GroupMapping Source

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

writeUserMappings Source

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 Source

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"