Second version of the interface containing extra functions for working with iptables. More...

#include <IDobbyUtils.h>

Inheritance diagram for IDobbyUtils_v2:

[legend]

Collaboration diagram for IDobbyUtils_v2:

Public Member Functions
virtual void	setIntegerMetaData (const ContainerId &id, const std::string &key, int value)=0
	Sets / Gets integer meta data for the given container. More...

virtual int	getIntegerMetaData (const ContainerId &id, const std::string &key, int defaultValue) const =0

int	getIntegerMetaData (const ContainerId &id, const std::string &key)

virtual void	setStringMetaData (const ContainerId &id, const std::string &key, const std::string &value)=0
	Sets / Gets string meta data for the given container. More...

virtual std::string	getStringMetaData (const ContainerId &id, const std::string &key, const std::string &defaultValue) const =0

std::string	getStringMetaData (const ContainerId &id, const std::string &key)

virtual void	clearContainerMetaData (const ContainerId &id)=0

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

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

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

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

Public Member Functions inherited from IDobbyUtils_v1
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

Additional Inherited Members
Protected Member Functions inherited from IDobbyUtils_v1
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

Second version of the interface containing extra functions for working with iptables.

Member Function Documentation

◆ cancelTimer()

virtual bool IDobbyUtils_v1::cancelTimer

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

◆ checkExtImageFile()

virtual bool IDobbyUtils_v1::checkExtImageFile

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.

◆ cleanMountLostAndFound()

virtual void IDobbyUtils_v1::cleanMountLostAndFound

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.

◆ deviceAllowed()

virtual bool IDobbyUtils_v1::deviceAllowed

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.

◆ formatExtImageFile()

virtual bool IDobbyUtils_v1::formatExtImageFile

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.

◆ getDriverMajorNumber()

virtual unsigned int IDobbyUtils_v1::getDriverMajorNumber

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.

◆ getGID()

virtual gid_t IDobbyUtils_v1::getGID

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

◆ getNamespaceFd()

virtual int IDobbyUtils_v1::getNamespaceFd

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

◆ getUID()

virtual uid_t IDobbyUtils_v1::getUID

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

◆ loopDeviceAssociate()

virtual int IDobbyUtils_v1::loopDeviceAssociate

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.

◆ mkdirRecursive()

virtual bool IDobbyUtils_v1::mkdirRecursive

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.

◆ readTextFile()

virtual std::string IDobbyUtils_v1::readTextFile

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.

◆ rmdirContents()

virtual bool IDobbyUtils_v1::rmdirContents

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.

◆ rmdirRecursive()

virtual bool IDobbyUtils_v1::rmdirRecursive

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.

◆ setIntegerMetaData()

virtual void IDobbyUtils_v2::setIntegerMetaData	(	const ContainerId &	id,
		const std::string &	key,
		int	value
	)

pure virtual

Sets / Gets integer meta data for the given container.

You can use this to share meta data about the container across different plugins. For example if network namespaces are enabled.

The data is cleared automatically when the container is shutdown.

Implemented in DobbyUtils.

◆ setStringMetaData()

virtual void IDobbyUtils_v2::setStringMetaData	(	const ContainerId &	id,
		const std::string &	key,
		const std::string &	value
	)

pure virtual

Sets / Gets string meta data for the given container.

You can use this to share meta data about the container across different plugins. For example the ip address assigned to the container.

The data is cleared automatically when the container is shutdown.

Implemented in DobbyUtils.

◆ writeTextFile()

virtual bool IDobbyUtils_v1::writeTextFile

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.

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

utils/include/IDobbyUtils.h

Public Member Functions

Additional Inherited Members

Detailed Description

Member Function Documentation

◆ cancelTimer()

◆ checkExtImageFile()

◆ cleanMountLostAndFound()

◆ deviceAllowed()

◆ formatExtImageFile()

◆ getDriverMajorNumber()

◆ getGID()

◆ getNamespaceFd()

◆ getUID()

◆ loopDeviceAssociate()

◆ mkdirRecursive()

◆ readTextFile()

◆ rmdirContents()

◆ rmdirRecursive()

◆ setIntegerMetaData()

◆ setStringMetaData()

◆ writeTextFile()