Dobby  3.0
Dobby “Docker based Thingy” is a tool for managing and running OCI containers using crun
Public Member Functions | List of all members
IDobbyUtils_v2 Class Referenceabstract

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

#include <IDobbyUtils.h>

Inheritance diagram for IDobbyUtils_v2:
Inheritance graph
[legend]
Collaboration diagram for IDobbyUtils_v2:
Collaboration graph
[legend]

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]timerIdThe 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]dirFdThe 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]imageFileNameThe name of the file to check.
[in]repairIf 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]mountPointThe absolute path to the mounted device, NOT the the location of the lost+found dir.
[in]logTagIf 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]majorThe major number of the device.
[in]minorThe 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]dirFdThe 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]imageFileNameThe name of the file to format, it must already exist.
[in]fsTypeThe 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]driverNameThe 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]pidThe 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]pidThe pid of the process to get the namespace of.
[in]nsTypeThe 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]pidThe 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]fileFdAn open file descriptor to associate with the loop device.
[out]loopDevPathIf 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]dirFdIf specified the path should be relative to to this directory.
[in]pathThe path to the directory to create.
[in]modeThe 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]dirFdIf specified the path should be relative to to this directory.
[in]pathThe path to file to write to.
[in]maxLenThe 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]dirFdIf specified the path should be relative to to this directory.
[in]pathThe path to the directory to create.
[in]modeThe 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]dirFdIf specified the path should be relative to to this directory.
[in]pathThe path to the directory to create.
[in]modeThe 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]dirFdIf specified the path should be relative to to this directory.
[in]pathThe path to file to write to.
[in]flagsOpen flags, these will be OR'd with O_WRONLY and O_CLOEXEC.
[in]modeThe 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: