Utility methods for hooks and the general containiser daemon. More...

#include <DobbyUtils.h>

Inheritance diagram for DobbyUtils:

[legend]

Collaboration diagram for DobbyUtils:

[legend]

Public Member Functions
int	loopDeviceAssociate (int fileFd, std::string *loopDevPath) const override
	Associates a give file descriptor with a loop device. More...

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

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

bool	mkdirRecursive (const std::string &path, mode_t mode) const override
	Makes a directory and all parent directories as needed. More...

bool	mkdirRecursive (int dirFd, const std::string &path, mode_t mode) const override
	Makes a directory and all parent directories as needed. More...

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

bool	rmdirRecursive (int dirFd, const std::string &path) const override
	Removes a directory and all it's contents. More...

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

bool	rmdirContents (int dirFd, const std::string &path) const override
	Removes the contents of a directory but leave the actual directory in place. More...

bool	rmdirContents (int dirFd) const override

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

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

bool	writeTextFileAt (int dirFd, const std::string &path, const std::string &str, int flags, mode_t mode) const override
	Simply writes a string into a file. More...

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

std::string	readTextFile (const std::string &path, size_t maxLen) const override
	Simply read a string from a file. More...

std::string	readTextFileAt (int dirFd, const std::string &path, size_t maxLen) const override
	Simply read a string from a file. More...

bool	cancelTimer (int timerId) const override
	Removes the given timer from the timer queue. More...

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

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

void	setIntegerMetaData (const ContainerId &id, const std::string &key, int value) override
	Sets / Gets integer meta data for the given container. More...

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

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

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

void	clearContainerMetaData (const ContainerId &id) override
	Clears all the meta data stored for a given container. More...

bool	insertEbtablesRule (const std::string &args) const override
	Inserts the given ebtables rule to the existing set. More...

bool	deleteEbtablesRule (const std::string &args) const override
	Deletes the given ebtables rule from the existing set. More...

uid_t	getUID (pid_t pid) const override
	Returns the UID for the given PID. More...

gid_t	getGID (pid_t pid) const override
	Returns the GID for the given PID. More...

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

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

Public Member Functions inherited from IDobbyUtils_v2
int	getIntegerMetaData (const ContainerId &id, const std::string &key)

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

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

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

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

Private Member Functions
int	openLoopDevice (std::string *loopDevice) const
	Attempts to open an available loop device. More...

bool	attachFileToLoopDevice (int loopFd, int fileFd) const
	Attempts to attach the file to the loop device. More...

int	runE2fsTool (int dirFd, std::list< std::string > consoleOutput, const char e2fsTool,...) const
	Run the E2FS tool inside the given directory with given args. More...

bool	callInNamespaceImpl (pid_t pid, int nsType, const std::function< bool()> &func) const override
	Utility function to run some code in a specific namespace of the container. More...

bool	callInNamespaceImpl (int namespaceFd, const std::function< bool()> &func) const override
	Utility function to run some code in a specific namespace of the container. More...

void	nsThread (int newNsFd, int nsType, bool *success, std::function< bool()> &func) const
	Thread helper function that implements the setns syscall. More...

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

void	buildDeviceWhitelist ()
	Builds the whitelist of allowed device numbers. More...

bool	executeCommand (const std::string &command) const

int	getGIDorUID (pid_t pid, const std::string &idType) const
	Returns the effective GID or UID for the given PID by parsing /proc/<PID>/status. More...

Static Private Member Functions
static bool	deleteRecursive (int dirfd, int depth)
	Recursive function that deletes everything within the supplied directory (as a descriptor).

Private Attributes
std::shared_ptr< DobbyTimer >	mTimerQueue

std::set< dev_t >	mDeviceWhitelist

std::mutex	mMajorNumberLock

std::map< std::string, unsigned int >	mMajorNumberCache

std::mutex	mMetaDataLock

std::map< std::pair< ContainerId, std::string >, int >	mIntegerMetaData

std::map< std::pair< ContainerId, std::string >, std::string >	mStringMetaData

Additional Inherited Members

Detailed Description

Utility methods for hooks and the general containiser daemon.

See also: IDobbyUtils

Member Function Documentation

◆ attachFileToLoopDevice()

bool DobbyUtils::attachFileToLoopDevice	(	int	loopFd,
		int	fileFd
	)		const

private

Attempts to attach the file to the loop device.

Returns: on success a positive file desccriptor corresponding to a free loop device, -1 on error.

◆ buildDeviceWhitelist()

void DobbyUtils::buildDeviceWhitelist ( )

private

Builds the whitelist of allowed device numbers.

At the moment only the following devices are added: hidraw, 0 - 100 input, 64 - 95

The list is exclusive of the opengl / graphics device nodes and the set of 'standard' device nodes.

◆ callInNamespaceImpl() [1/2]

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

overrideprivatevirtual

Utility function to run some code in a specific namespace of the container.

This function uses the setns syscall and therefore it must spawn a thread to run the callback in. However this function blocks until the thread completes, so although it is multi-threaded it's API is blocking, i.e. effectively single threaded.

Parameters

[in]	namespaceFd	The fd of the namespace to enter.
[in]	nsType	The namespace to run the function in, see above.
[in]	func	The function to execute.

Returns: true if successifully entered the namespace, otherwise false.

Implements IDobbyUtils_v1.

◆ callInNamespaceImpl() [2/2]

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

overrideprivatevirtual

Utility function to run some code in a specific namespace of the container.

This function uses the setns syscall and therefore it must spawn a thread to run the callback in. However this function blocks until the thread completes, so although it is multi-threaded it's API is blocking, i.e. effectively single threaded.

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

Parameters

[in]	pid	The pid of the process namespace to enter.
[in]	nsType	The namespace to run the function in, see above.
[in]	func	The function to execute.

Returns: true if successifully entered the namespace, otherwise false.

Implements IDobbyUtils_v1.

◆ cancelTimer()

bool DobbyUtils::cancelTimer ( int timerId ) const

overridevirtual

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

Implements IDobbyUtils_v1.

◆ checkExtImageFile()

bool DobbyUtils::checkExtImageFile	(	int	dirFd,
		const std::string &	imageFileName,
		bool	repair
	)		const

overridevirtual

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

Implements IDobbyUtils_v1.

◆ cleanMountLostAndFound()

void DobbyUtils::cleanMountLostAndFound	(	const std::string &	mountPoint,
		const std::string &	logTag
	)		const

overridevirtual

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.

Implements IDobbyUtils_v1.

◆ clearContainerMetaData()

void DobbyUtils::clearContainerMetaData ( const ContainerId & id )

overridevirtual

Clears all the meta data stored for a given container.

This is called by the DobbyManager when a container is starting or has just stopped.

Implements IDobbyUtils_v2.

◆ deleteEbtablesRule()

bool DobbyUtils::deleteEbtablesRule ( const std::string & args ) const

overridevirtual

Deletes the given ebtables rule from the existing set.

This only performs a delete, if the a rule is not currently installed then false is returned

Parameters

[in] args The set of one rule to remove.

Returns: true if the rules were removed, otherwise false.

Implements IDobbyUtils_v3.

◆ deviceAllowed()

bool DobbyUtils::deviceAllowed ( dev_t device ) const

overridevirtual

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] device The device number.

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

Implements IDobbyUtils_v1.

◆ formatExtImageFile()

bool DobbyUtils::formatExtImageFile	(	int	dirFd,
		const std::string &	imageFileName,
		const std::string &	fsType
	)		const

overridevirtual

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

Implements IDobbyUtils_v1.

◆ getDriverMajorNumber()

unsigned int DobbyUtils::getDriverMajorNumber ( const std::string & driverName ) const

overridevirtual

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.

Implements IDobbyUtils_v1.

◆ getGID()

gid_t DobbyUtils::getGID ( pid_t pid ) const

overridevirtual

Returns the GID for the given PID.

Parameters

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

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

Implements IDobbyUtils_v1.

◆ getGIDorUID()

int DobbyUtils::getGIDorUID	(	pid_t	pid,
		const std::string &	idType
	)		const

private

Returns the effective GID or UID for the given PID by parsing /proc/<PID>/status.

Parameters

[in]	pid	The PID of the process to get the GID for
[in]	idType	The type of ID to get, either "Gid" or "Uid"

Returns: the GID or UID of the process, or -1 if the ID could not be found

◆ getNamespaceFd()

int DobbyUtils::getNamespaceFd	(	pid_t	pid,
		int	nsType
	)		const

overridevirtual

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

Implements IDobbyUtils_v1.

◆ getUID()

uid_t DobbyUtils::getUID ( pid_t pid ) const

overridevirtual

Returns the UID for the given PID.

Parameters

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

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

Implements IDobbyUtils_v1.

◆ insertEbtablesRule()

bool DobbyUtils::insertEbtablesRule ( const std::string & args ) const

overridevirtual

Inserts the given ebtables rule to the existing set.

This doesn't flush out any old rules, it just adds the new one at the beginning of the table.

Parameters

[in] args The args of one rule to add.

Returns: true if the rule was added, otherwise false.

Implements IDobbyUtils_v3.

◆ loopDeviceAssociate()

int DobbyUtils::loopDeviceAssociate	(	int	fileFd,
		std::string *	loopDevPath
	)		const

overridevirtual

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.

Implements IDobbyUtils_v1.

◆ mkdirRecursive() [1/2]

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

overridevirtual

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.

Implements IDobbyUtils_v1.

◆ mkdirRecursive() [2/2]

bool DobbyUtils::mkdirRecursive	(	int	dirFd,
		const std::string &	path,
		mode_t	mode
	)		const

overridevirtual

Makes a directory and all parent directories as needed.

This is equivalent to the 'mkdir -p' 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 path 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.

Implements IDobbyUtils_v1.

◆ nsThread()

void DobbyUtils::nsThread	(	int	newNsFd,
		int	nsType,
		bool *	success,
		std::function< bool()> &	func
	)		const

private

Thread helper function that implements the setns syscall.

This must be executed as a thread as it calls setns which switches namespaces and you don't really want to do this in the main thread.

Parameters

[in]	newNsFd	The namespace to switch into.
[in]	func	The function to execute in the new namespace.

Returns: true if successifully entered the namespace, otherwise false.

◆ openLoopDevice()

int DobbyUtils::openLoopDevice ( std::string * loopDevice ) const

private

Attempts to open an available loop device.

Returns: on success a positive file desccriptor corresponding to a free loop device, -1 on error.

◆ readTextFile()

std::string DobbyUtils::readTextFile	(	const std::string &	path,
		size_t	maxLen
	)		const

overridevirtual

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.

Implements IDobbyUtils_v1.

◆ readTextFileAt()

std::string DobbyUtils::readTextFileAt	(	int	dirFd,
		const std::string &	path,
		size_t	maxLen
	)		const

overridevirtual

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.

Implements IDobbyUtils_v1.

◆ rmdirContents() [1/2]

bool DobbyUtils::rmdirContents ( const std::string & path ) const

overridevirtual

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.

Implements IDobbyUtils_v1.

◆ rmdirContents() [2/2]

bool DobbyUtils::rmdirContents	(	int	dirFd,
		const std::string &	path
	)		const

overridevirtual

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

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

If the pathname given in path 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.

Implements IDobbyUtils_v1.

◆ rmdirRecursive() [1/2]

bool DobbyUtils::rmdirRecursive ( const std::string & path ) const

overridevirtual

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.

Implements IDobbyUtils_v1.

◆ rmdirRecursive() [2/2]

bool DobbyUtils::rmdirRecursive	(	int	dirFd,
		const std::string &	path
	)		const

overridevirtual

Removes a directory and all it's contents.

This is equivalent to the 'rm -rf' 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.

Implements IDobbyUtils_v1.

◆ runE2fsTool()

int DobbyUtils::runE2fsTool	(	int	dirFd,
		std::list< std::string > *	consoleOutput,
		const char *	e2fsTool,
			...
	)		const

private

Run the E2FS tool inside the given directory with given args.

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 image to check. The function will switch to this directory before dropping permissions (provided it's not AT_FCWD).
[out]	consoleOutput	String list to store the lines of output from the tool.
[in]	e2fsTool	The tool to run, should be either "e2fsck" or "mke2fs".
[in]	...	Extra arguments to supply to the tool.

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

◆ setIntegerMetaData()

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

overridevirtual

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.

Implements IDobbyUtils_v2.

◆ setStringMetaData()

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

overridevirtual

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.

Implements IDobbyUtils_v2.

◆ startTimerImpl()

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

overrideprivatevirtual

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.

Implements IDobbyUtils_v1.

◆ writeTextFile()

bool DobbyUtils::writeTextFile	(	const std::string &	path,
		const std::string &	str,
		int	flags,
		mode_t	mode
	)		const

overridevirtual

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.

Implements IDobbyUtils_v1.

◆ writeTextFileAt()

bool DobbyUtils::writeTextFileAt	(	int	dirFd,
		const std::string &	path,
		const std::string &	str,
		int	flags,
		mode_t	mode
	)		const

overridevirtual

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.

Implements IDobbyUtils_v1.

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

utils/include/DobbyUtils.h
utils/source/DobbyUtils.cpp

Public Member Functions

Private Member Functions

Static Private Member Functions

Private Attributes

Additional Inherited Members

Detailed Description

Member Function Documentation

◆ attachFileToLoopDevice()

◆ buildDeviceWhitelist()

◆ callInNamespaceImpl() [1/2]

◆ callInNamespaceImpl() [2/2]

◆ cancelTimer()

◆ checkExtImageFile()

◆ cleanMountLostAndFound()

◆ clearContainerMetaData()

◆ deleteEbtablesRule()

◆ deviceAllowed()

◆ formatExtImageFile()

◆ getDriverMajorNumber()

◆ getGID()

◆ getGIDorUID()

◆ getNamespaceFd()

◆ getUID()

◆ insertEbtablesRule()

◆ loopDeviceAssociate()

◆ mkdirRecursive() [1/2]

◆ mkdirRecursive() [2/2]

◆ nsThread()

◆ openLoopDevice()

◆ readTextFile()

◆ readTextFileAt()

◆ rmdirContents() [1/2]

◆ rmdirContents() [2/2]

◆ rmdirRecursive() [1/2]

◆ rmdirRecursive() [2/2]

◆ runE2fsTool()

◆ setIntegerMetaData()

◆ setStringMetaData()

◆ startTimerImpl()

◆ writeTextFile()

◆ writeTextFileAt()