blob: bb400383eb277886563efe249465eef185fde451 [file] [log] [blame]
// Licensed to the Apache Software Foundation (ASF) under one
// or more contributor license agreements. See the NOTICE file
// distributed with this work for additional information
// regarding copyright ownership. The ASF licenses this file
// to you under the Apache License, Version 2.0 (the
// "License"); you may not use this file except in compliance
// with the License. You may obtain a copy of the License at
// Unless required by applicable law or agreed to in writing, software
// distributed under the License is distributed on an "AS IS" BASIS,
// See the License for the specific language governing permissions and
// limitations under the License.
#ifndef __LINUX_NS_HPP__
#define __LINUX_NS_HPP__
// This file contains Linux-only OS utilities.
#ifndef __linux__
#error "linux/ns.hpp is only available on Linux systems."
#include <sched.h>
#include <sys/syscall.h>
#include <queue>
#include <set>
#include <string>
#include <thread>
#include <process/future.hpp>
#include <stout/lambda.hpp>
#include <stout/nothing.hpp>
#include <stout/option.hpp>
#include <stout/result.hpp>
#include <stout/try.hpp>
#define CLONE_NEWNS 0x00020000
#define CLONE_NEWUTS 0x04000000
#define CLONE_NEWIPC 0x08000000
#define CLONE_NEWPID 0x20000000
#define CLONE_NEWNET 0x40000000
#define CLONE_NEWUSER 0x10000000
#define CLONE_NEWCGROUP 0x02000000
// Define a 'setns' for compilation environments that don't already
// have one.
inline int setns(int fd, int nstype)
#ifdef SYS_setns
return ::syscall(SYS_setns, fd, nstype);
#elif defined(__x86_64__)
// A workaround for those hosts that have an old glibc (older than
// 2.14) but have a new kernel. The magic number '308' here is the
// syscall number for 'setns' on x86_64 architecture.
return ::syscall(308, fd, nstype);
#error "setns is not available"
namespace ns {
// Returns the nstype (e.g., CLONE_NEWNET, CLONE_NEWNS, etc.) for the
// given namespace which can be used when calling ::setns.
Try<int> nstype(const std::string& ns);
// Given a single CLONE_NEW* constant, return the corresponding namespace
// name. This is the inverse of ns::nstype().
Try<std::string> nsname(int nsType);
// Returns all the configured kernel namespaces.
std::set<int> nstypes();
// Returns true if all the given CLONE_NEW* constants are supported
// in the running kernel. If CLONE_NEWUSER is specified, the kernel
// version must be at least 3.12.0 since prior to that version, major
// kernel subsystems (e.g. XFS) did not implement user namespace
// support. See also user_namespaces(7).
Try<bool> supported(int nsTypes);
// Re-associate the calling process with the specified namespace. The
// path refers to one of the corresponding namespace entries in the
// /proc/[pid]/ns/ directory (or bind mounted elsewhere). We do not
// allow a process with multiple threads to call this function because
// it will lead to some weird situations where different threads of a
// process are in different namespaces.
Try<Nothing> setns(
const std::string& path,
const std::string& ns,
bool checkMultithreaded = true);
// Re-associate the calling process with the specified namespace. The
// pid specifies the process whose namespace we will associate.
Try<Nothing> setns(
pid_t pid,
const std::string& ns,
bool checkMultithreaded = true);
// Get the inode number of the specified namespace for the specified
// pid. The inode number identifies the namespace and can be used for
// comparisons, i.e., two processes with the same inode for a given
// namespace type are in the same namespace.
Result<ino_t> getns(pid_t pid, const std::string& ns);
* Performs an `os::clone` after entering a set of namespaces for the
* specified `target` process.
* This function provides two steps of functionality:
* (1) Enter a set of namespaces via two `fork` calls.
* (1) Perform a `clone` within that set of namespaces.
* Step (1) of functionality is similar to the `nsenter` command line
* utility. Step (2) allows us to perform a clone that itself might
* create a nested set of namespaces, which enables us to have nested
* containers.
* Double Fork:
* In order to enter a PID namespace we need to do a double fork
* because doing a `setns` for a PID namespace only effects future
* children.
* Moreover, attempting to `setns` before we do any forks and then
* have the parent `setns` back to the original namespaces does not
* work because entering a depriviledged user namespace will not let
* us reassociate back with the original namespace, even if we keep
* the file descriptor of the original namespace open.
* Because we have to double fork we need to send back the actual PID
* of the final process that's executing the provided function `f`.
* We use domain sockets for this because in the event we've entered a
* PID namespace we need the kernel to translate the PID to the PID in
* our PID namespace.
* @param target Target process whose namespaces we should enter.
* @param nstypes Namespaces we should enter.
* @param f Function to invoke after entering the namespaces and cloning.
* @param flags Flags to pass to `clone`.
* @return `pid_t` of the child process.
Try<pid_t> clone(
pid_t target,
int nstypes,
const lambda::function<int()>& f,
int flags);
// Returns the namespace flags in the string form of bitwise-ORing the
// flags, e.g., CLONE_NEWNS | CLONE_NEWNET.
std::string stringify(int flags);
// The NamespaceRunner runs any function in a specified namespace.
// To do that it manages a separate thread which would be re-associated
// with that namespace.
class NamespaceRunner
// Start the looper thread.
thread.reset(new std::thread(&NamespaceRunner::loop, this));
// Shutdown the queue.
// Wait for the thread to complete.
// Run any function in a specified namespace.
template <typename T>
process::Future<T> run(
const std::string& path,
const std::string& ns,
const lambda::function<Try<T>()>& func)
std::shared_ptr<process::Promise<T>> promise(
new process::Promise<T>);
process::Future<T> future = promise->future();
// Put a function to the queue, the function will be called
// in the thread. The thread will be re-associated with the
// specified namespace.
Try<Nothing> setns = ::ns::setns(path, ns, false);
if (setns.isError()) {
} else {
return future;
typedef lambda::function<void()> Func;
// The thread loop.
void loop()
for (;;) {
// Get a function from the queue.
Option<Func> func = queue.get();
// Stop the thread if the queue is shutdowned.
if (func.isNone()) {
// Call the function, it re-associates the thread with the
// specified namespace and calls the initial user function.
// It's not safe to use process::Queue when not all of its callers are
// managed by libprocess. Calling Future::await() in looper thread
// might cause the looper thread to be donated to a libprocess Process.
// If that Process is very busy (e.g., master or agent Process), it's
// possible that the looper thread will never re-gain control.
// ProcessingQueue uses mutex and condition variable to solve this
// problem. ProcessingQueue::get() can block the thread. The main
// use cases for the class are thread workers and thread pools.
template <typename T>
class ProcessingQueue
ProcessingQueue() : finished(false) {}
~ProcessingQueue() = default;
// Add an element to the queue and notify one client.
void put(T&& t)
synchronized (mutex) {
// NOTE: This function blocks the thread. It returns the oldest
// element from the queue and returns None() if the queue is
// shutdowned.
Option<T> get()
synchronized (mutex) {
// Wait for either a new queue element or queue shutdown.
while (queue.empty() && !finished) {
synchronized_wait(&cond, &mutex);
if (finished) {
// The queue is shutdowned.
return None();
// Return the oldest element from the queue.
T t = std::move(queue.front());
return Some(std::move(t));
// Shutdown the queue and notify all clients.
void shutdown() {
synchronized (mutex) {
finished = true;
std::mutex mutex;
std::condition_variable cond;
std::queue<T> queue;
bool finished;
ProcessingQueue<Func> queue;
std::unique_ptr<std::thread> thread;
} // namespace ns {
#endif // __LINUX_NS_HPP__