Interface that exports some utilities that plugins may find useful. More...

#include <IDobbyIPCUtils.h>

Inheritance diagram for IDobbyUtils_v1:

[legend]

Public Member Functions
virtual bool	mkdirRecursive (const std::string &path, mode_t mode) const =0
	Makes a directory and all parent directories as needed. More...

virtual bool	mkdirRecursive (int dirFd, const std::string &path, mode_t mode) const =0

virtual bool	rmdirRecursive (const std::string &path) const =0
	Removes a directory and all it's contents. More...

virtual bool	rmdirRecursive (int dirFd, const std::string &path) const =0

virtual bool	rmdirContents (const std::string &path) const =0
	Removes the contents of a directory but leave the actual directory in place. More...

virtual bool	rmdirContents (int dirFd, const std::string &path) const =0

virtual bool	rmdirContents (int dirFd) const =0

virtual int	loopDeviceAssociate (int fileFd, std::string *loopDevPath=nullptr) const =0
	Associates a give file descriptor with a loop device. More...

virtual bool	checkExtImageFile (int dirFd, const std::string &imageFileName, bool repair=true) const =0
	Runs the e2fsck tool on a file system image to check it's integrity. More...

virtual bool	formatExtImageFile (int dirFd, const std::string &imageFileName, const std::string &fsType="ext4") const =0
	Runs the mke2fs tool to format a file system image. More...

virtual void	cleanMountLostAndFound (const std::string &mountPoint, const std::string &logTag=std::string()) const =0
	Logs and deletes any files found in the lost+found directory of the mount point. More...

virtual bool	writeTextFile (const std::string &path, const std::string &str, int flags, mode_t mode=0644) const =0
	Simply writes a string into a file. More...

virtual bool	writeTextFileAt (int dirFd, const std::string &path, const std::string &str, int flags, mode_t mode=0644) const =0

virtual std::string	readTextFile (const std::string &path, size_t maxLen=4096) const =0
	Simply read a string from a file. More...

virtual std::string	readTextFileAt (int dirFd, const std::string &path, size_t maxLen=4096) const =0

virtual int	getNamespaceFd (pid_t pid, int nsType) const =0
	Returns a file descriptor to the given namespace of the process. More...

template<class Function >
bool	callInNamespace (pid_t pid, int nsType, Function func) const
	Calls the given function in the namespace of given pid. More...

template<class Function , class... Args>
bool	callInNamespace (pid_t pid, int nsType, Function &&f, Args &&... args) const
	Slightly nicer version of callInNamespace, handles the function bind for you automatically. More...

template<class Rep , class Period >
int	startTimer (const std::chrono::duration< Rep, Period > &timeout, bool oneShot, const std::function< bool()> &handler) const
	Adds a new timer to the timer queue. More...

virtual bool	cancelTimer (int timerId) const =0
	Removes the given timer from the timer queue. More...

template<class Function >
bool	callInNamespace (int namespaceFd, Function func) const
	Call the given function in the namespace of the descriptor. More...

template<class Function , class... Args>
bool	callInNamespace (int namespaceFd, Function &&f, Args &&... args) const

virtual unsigned int	getDriverMajorNumber (const std::string &driverName) const =0
	Returns the major number assigned to a given driver. More...

virtual bool	deviceAllowed (dev_t device) const =0
	Returns true if the given device is allowed in the container. More...

bool	deviceAllowed (unsigned int major, unsigned int minor) const

Protected Member Functions
virtual bool	callInNamespaceImpl (pid_t pid, int nsType, const std::function< bool()> &func) const =0
	Implementation of the callInNamespace public interface. More...

virtual bool	callInNamespaceImpl (int namespaceFd, const std::function< bool()> &func) const =0
	Implementation of the callInNamespace public interface. More...

virtual int	startTimerImpl (const std::chrono::milliseconds &timeout, bool oneShot, const std::function< bool()> &handler) const =0
	Adds a new timer to the timer queue. More...

virtual gid_t	getGID (pid_t pid) const =0
	Returns the GID for the given PID. More...

virtual uid_t	getUID (pid_t pid) const =0
	Returns the UID for the given PID. More...

Detailed Description

Interface that exports some utilities that plugins may find useful.

As it's name implies this is just a collection of standalone utility functions that wrap up some of the common things that plugins do.

Member Function Documentation

◆ callInNamespace() [1/3]

template<class Function >

bool IDobbyUtils_v1::callInNamespace	(	int	namespaceFd,
		Function	func
	)		const

inline

Call the given function in the namespace of the descriptor.

To get a namespace descriptor of a given process you just need to open one of the files in /proc/<pid>/ns/

Parameters

[in]	namespaceFd	The namespace file descriptor to run the function in.
[in]	func	The actual function to execute.

Returns: true on success, false on failure.

◆ callInNamespace() [2/3]

template<class Function , class... Args>

bool IDobbyUtils_v1::callInNamespace	(	pid_t	pid,
		int	nsType,
		Function &&	f,
		Args &&...	args
	)		const

inline

Slightly nicer version of callInNamespace, handles the function bind for you automatically.

See above version for details on the function.

Parameters

[in]	pid	The pid owner of the namespace to enter, typically the pid of the process in the container.
[in]	nsType	The type of the namespace to enter, see above.
[in]	func	The actual function to execute.

Returns: true on success, false on failure.

◆ callInNamespace() [3/3]

template<class Function >

bool IDobbyUtils_v1::callInNamespace	(	pid_t	pid,
		int	nsType,
		Function	func
	)		const

inline

Calls the given function in the namespace of given pid.

You'd typically use this to perform options in the namespace of a container. The pid argument would be the pid of the containered processes as passed in one of the pre/post hook functions.

The nsType argument should be one of the following values: CLONE_NEWIPC - run in a IPC namespace CLONE_NEWNET - run in a network namespace CLONE_NEWNS - run in a mount namespace CLONE_NEWPID - run in a PID namespace CLONE_NEWUSER - run in a user namespace CLONE_NEWUTS - run in a UTS namespace

The following is an example of how you could create a listening socket within a container

TODO:

Parameters

[in]	pid	The pid owner of the namespace to enter, typically the pid of the process in the container.
[in]	nsType	The type of the namespace to enter, see above.
[in]	func	The actual function to execute.

Returns: true on success, false on failure.

◆ callInNamespaceImpl() [1/2]

virtual bool IDobbyUtils_v1::callInNamespaceImpl	(	int	namespaceFd,
		const std::function< bool()> &	func
	)		const

protectedpure virtual

Implementation of the callInNamespace public interface.

See also: IDobbyUtils::callInNamespace

Parameters

[in]	namespaceFd	The namespace file descriptor to run the function in.
[in]	func	The actual function to execute.

Returns: true on success, false on failure.

Implemented in DobbyUtils.

◆ callInNamespaceImpl() [2/2]

virtual bool IDobbyUtils_v1::callInNamespaceImpl	(	pid_t	pid,
		int	nsType,
		const std::function< bool()> &	func
	)		const

protectedpure virtual

Implementation of the callInNamespace public interface.

See also: IDobbyUtils::callInNamespace

Parameters

[in]	pid	The pid owner of the namespace to enter, typically the pid of the process in the container.
[in]	nsType	The type of the namespace to enter, see above.
[in]	func	The actual function to execute.

Returns: true on success, false on failure.

Implemented in DobbyUtils.

◆ cancelTimer()

virtual bool IDobbyUtils_v1::cancelTimer ( int timerId ) const

pure virtual

Removes the given timer from the timer queue.

Once this method returns (successfully) you are guaranteed that the timer handler will not be called, i.e. this is synchronisation point.

This method will fail if called from the context of a timer handler, if you want to cancel a repeating timer then just return false in the handler.

Parameters

[in] timerId The id of the timer to cancel as returned by the startTimer() method.

Returns: true if the timer was found and was removed from the queue, otherwise false

Implemented in DobbyUtils.

◆ checkExtImageFile()

virtual bool IDobbyUtils_v1::checkExtImageFile	(	int	dirFd,
		const std::string &	imageFileName,
		bool	repair = `true`
	)		const

pure virtual

Runs the e2fsck tool on a file system image to check it's integrity.

This function does a fork/exec to launch the process, it drops root privileges and runs the tool as user 1000:1000, therefore the file that is being checked should be readable and writeble by user 1000.

If this function returns false the image file should probably be deleted / reformatted.

Parameters

[in]	dirFd	The fd of the directory containing the the image to check. The function will switch to this directory before dropping permissions (provided it's not AT_FCWD).
[in]	imageFileName	The name of the file to check.
[in]	repair	If true we'll ask the tool to try and repair the file if it detects any errors.

Returns: if the file passes the check (or was successifully repaired) true is returned, otherwise false.

Implemented in DobbyUtils.

◆ cleanMountLostAndFound()

virtual void IDobbyUtils_v1::cleanMountLostAndFound	(	const std::string &	mountPoint,
		const std::string &	logTag = `std::string()`
	)		const

pure virtual

Logs and deletes any files found in the lost+found directory of the mount point.

We should be clearing the lost+found to avoid cruft building up and taking all the space in the loop mount.

Parameters

[in]	mountPoint	The absolute path to the mounted device, NOT the the location of the lost+found dir.
[in]	logTag	If not empty then a log warning message will be printed containing the name of the file that was deleted and referencing the the string in logTag.

Implemented in DobbyUtils.

◆ deviceAllowed()

virtual bool IDobbyUtils_v1::deviceAllowed ( dev_t device ) const

pure virtual

Returns true if the given device is allowed in the container.

This is here for security reasons as I didn't want just any device added to the container whitelist. If we trust the code on the other end of Dobby that is creating the containers then this is not needed, but just in case that got hacked I didn't want people to create containers enabling access to CDI / system device nodes.

Warning: This method doesn't take into account drivers being insmod / rmmod and the re-use of major numbers, however if a user could do that then this check is the least of our problems.

Parameters

[in]	major	The major number of the device.
[in]	minor	The minor number of the device.

Returns: true if the device is allowed, otherwise false.

Implemented in DobbyUtils.

◆ formatExtImageFile()

virtual bool IDobbyUtils_v1::formatExtImageFile	(	int	dirFd,
		const std::string &	imageFileName,
		const std::string &	fsType = `"ext4"`
	)		const

pure virtual

Runs the mke2fs tool to format a file system image.

This function does a fork/exec to launch the process, it drops root privileges and runs the tool as user 1000:1000, therefore the file that it's formatting should be readable and writeble by user 1000.

Parameters

[in]	dirFd	The fd of the directory containing the the image to write. The function will switch to this directory before dropping permissions (provided it's not AT_FCWD).
[in]	imageFileName	The name of the file to format, it must already exist.
[in]	fsType	The ext version to format the file as, this is equivalent to the '-t' option and should be one of; 'ext2', 'ext3' or 'ext4'

Returns: on success returns true on failure false.

Implemented in DobbyUtils.

◆ getDriverMajorNumber()

virtual unsigned int IDobbyUtils_v1::getDriverMajorNumber ( const std::string & driverName ) const

pure virtual

Returns the major number assigned to a given driver.

This function tries to find the major number assigned to a given driver, it does this by parsing the /proc/devices file.

Warning: Currently this function doesn't work for 'misc' devices, which are devices listed by /proc/misc.

Parameters

[in] driverName The name of the driver to get the major number for.

Returns: if found the major number is returned, if not found then 0 is returned.

Implemented in DobbyUtils.

◆ getGID()

virtual gid_t IDobbyUtils_v1::getGID ( pid_t pid ) const

protectedpure virtual

Returns the GID for the given PID.

See also: IDobbyUtils::getGID

Parameters

[in] pid The PID of the process to get the GID for

Returns: the GID of the process, or 0 if the GID could not be found

Implemented in DobbyUtils.

◆ getNamespaceFd()

virtual int IDobbyUtils_v1::getNamespaceFd	(	pid_t	pid,
		int	nsType
	)		const

pure virtual

Returns a file descriptor to the given namespace of the process.

The caller is responsible for closing the returned file descriptor when it is no longer required.

The returned namespace can used in the setns(...) call, or other calls that enter / manipulate namespaces.

Parameters

[in]	pid	The pid of the process to get the namespace of.
[in]	nsType	The type of namespace to get, it should be one of the CLONE_NEWxxx constants, see the setns man page for possible values.

Returns: on success the file descriptor to the given namespace, on failure -1

Implemented in DobbyUtils.

◆ getUID()

virtual uid_t IDobbyUtils_v1::getUID ( pid_t pid ) const

protectedpure virtual

Returns the UID for the given PID.

See also: IDobbyUtils::getUID

Parameters

[in] pid The PID of the process to get the UID for

Returns: the UID of the process, or 0 if the UID could not be found

Implemented in DobbyUtils.

◆ loopDeviceAssociate()

virtual int IDobbyUtils_v1::loopDeviceAssociate	(	int	fileFd,
		std::string *	loopDevPath = `nullptr`
	)		const

pure virtual

Associates a give file descriptor with a loop device.

First the function attempts to get a free loop device, if that succeeds it attaches the supplied file descriptor to it and returns an fd to the loop device and (optionally) writes the path to the loop device in the loopDevPath string.

Parameters

[in]	fileFd	An open file descriptor to associate with the loop device.
[out]	loopDevPath	If not null, the method will write the path to the loop device dev node into the string

Returns: on success returns the open file descriptor to the loop device associated with the file, on failure -1.

Implemented in DobbyUtils.

◆ mkdirRecursive()

virtual bool IDobbyUtils_v1::mkdirRecursive	(	const std::string &	path,
		mode_t	mode
	)		const

pure virtual

Makes a directory and all parent directories as needed.

This is equivalent to the 'mkdir -p <dir>' command.

All directories created will have access mode set by mode, for this reason the mode should be at least 'rwx---—'.

If the pathname given in pathname is relative, then it is interpreted relative to the directory referred to by the file descriptor dirFd, if dirFd is not supplied then it's relative to the cwd.

Parameters

[in]	dirFd	If specified the path should be relative to to this directory.
[in]	path	The path to the directory to create.
[in]	mode	The file access mode to give to all directories created.

Returns: true on success, false on failure.

Implemented in DobbyUtils.

◆ readTextFile()

virtual std::string IDobbyUtils_v1::readTextFile	(	const std::string &	path,
		size_t	maxLen = `4096`
	)		const

pure virtual

Simply read a string from a file.

Not much more to say really.

If the pathname given in filePath is relative, then it is interpreted relative to the directory referred to by the file descriptor dirFd, if dirFd is not supplied then it's relative to the cwd.

Parameters

[in]	dirFd	If specified the path should be relative to to this directory.
[in]	path	The path to file to write to.
[in]	maxLen	The maximum number of characters to read, defaults to 4096.

Returns: the string read from the file, on failure an empty string.

Implemented in DobbyUtils.

◆ rmdirContents()

virtual bool IDobbyUtils_v1::rmdirContents ( const std::string & path ) const

pure virtual

Removes the contents of a directory but leave the actual directory in place.

This is equivalent to the 'rm -rf <dir>/ *' command.

If the pathname given in pathname is relative, then it is interpreted relative to the directory referred to by the file descriptor dirFd, if dirFd is not supplied then it's relative to the cwd.

Warning: This function only supports deleting directories with contents that are less than 128 levels deep, this is to avoid running out of file descriptors.

Parameters

[in]	dirFd	If specified the path should be relative to to this directory.
[in]	path	The path to the directory to create.
[in]	mode	The file access mode to give to all directories created.

Returns: true on success, false on failure.

Implemented in DobbyUtils.

◆ rmdirRecursive()

virtual bool IDobbyUtils_v1::rmdirRecursive ( const std::string & path ) const

pure virtual

Removes a directory and all it's contents.

This is equivalent to the 'rm -rf <dir>' command.

If the pathname given in pathname is relative, then it is interpreted relative to the directory referred to by the file descriptor dirFd, if dirFd is not supplied then it's relative to the cwd.

Warning: This function only supports deleting directories with contents that are less than 128 levels deep, this is to avoid running out of file descriptors.

Parameters

[in]	dirFd	If specified the path should be relative to to this directory.
[in]	path	The path to the directory to create.
[in]	mode	The file access mode to give to all directories created.

Returns: true on success, false on failure.

Implemented in DobbyUtils.

◆ startTimer()

template<class Rep , class Period >

int IDobbyUtils_v1::startTimer	(	const std::chrono::duration< Rep, Period > &	timeout,
		bool	oneShot,
		const std::function< bool()> &	handler
	)		const

inline

Adds a new timer to the timer queue.

The handler function will be called after the timeout period and then if oneShot is false periodically at the given timeout interval.

The handler will be called from the context of the timer queue, bare in mind for any locking restrictions.

A timer can be cancelled by either calling cancelTimer() or returning false from the handler. One shot timers are automatically removed after they are fired, there is not need to call cancelTimer() for them.

Parameters

[in]	timeout	The time after which to call the supplied handler.
[in]	oneShot	If true the timer is automatically removed after it times out the first time.
[in]	handler	The handler function to call when the timer times out.

Returns: on success returns a (greater than zero) timer id integer which identifies the timer, on failure -1 is returned.

◆ startTimerImpl()

virtual int IDobbyUtils_v1::startTimerImpl	(	const std::chrono::milliseconds &	timeout,
		bool	oneShot,
		const std::function< bool()> &	handler
	)		const

protectedpure virtual

Adds a new timer to the timer queue.

See also: IDobbyUtils::startTimer

Parameters

[in]	timeout	The time after which to call the supplied handler.
[in]	oneShot	If true the timer is automatically removed after it times out the first time.
[in]	handler	The handler function to call when the timer times out.

Returns: on success returns a (greater than zero) timer id integer which identifies the timer, on failure -1 is returned.

Implemented in DobbyUtils.

◆ writeTextFile()

virtual bool IDobbyUtils_v1::writeTextFile	(	const std::string &	path,
		const std::string &	str,
		int	flags,
		mode_t	mode = `0644`
	)		const

pure virtual

Simply writes a string into a file.

Not much more to say really.

If the pathname given in filePath is relative, then it is interpreted relative to the directory referred to by the file descriptor dirFd, if dirFd is not supplied then it's relative to the cwd.

Parameters

[in]	dirFd	If specified the path should be relative to to this directory.
[in]	path	The path to file to write to.
[in]	flags	Open flags, these will be OR'd with O_WRONLY and O_CLOEXEC.
[in]	mode	The file access mode to set if O_CREAT was specified in flags and the file was created.

Returns: true on success, false on failure.

Implemented in DobbyUtils.

The documentation for this class was generated from the following file:

utils/include/IDobbyUtils.h

Public Member Functions

Protected Member Functions

Detailed Description

Member Function Documentation

◆ callInNamespace() [1/3]

◆ callInNamespace() [2/3]

◆ callInNamespace() [3/3]

◆ callInNamespaceImpl() [1/2]

◆ callInNamespaceImpl() [2/2]

◆ cancelTimer()

◆ checkExtImageFile()

◆ cleanMountLostAndFound()

◆ deviceAllowed()

◆ formatExtImageFile()

◆ getDriverMajorNumber()

◆ getGID()

◆ getNamespaceFd()

◆ getUID()

◆ loopDeviceAssociate()

◆ mkdirRecursive()

◆ readTextFile()

◆ rmdirContents()

◆ rmdirRecursive()

◆ startTimer()

◆ startTimerImpl()

◆ writeTextFile()