The registry

Each user’s settings are stored in a “registry”. This is a git repository with a set of json files which store the state of the subuser installation.

class subuserlib.classes.registry.Registry(user, gitReadHash='master', ignoreVersionLocks=False, initialized=False)

cleanOutOldPermissions()

commit(message=None)

Git commit the changes to the registry files, installed-miages.json and subusers.json.

ensureGitRepoInitialized()

getGitReadHash()

getGitRepository()

getLock()

To be used with with.

getLogOutputVerbosity()

getRepositories()

getSubusers()

log(message, verbosityLevel=1)

If the current verbosity level is equal to or greater than verbosityLevel, print the message to the screen. If the current verbosity level is equal to or greater than verbosityLevel minus one, add the message to the log. Do not mark the registry as changed.

logChange(message, verbosityLevel=1)

Add a log message to the registry’s change log, and mark the registry as changed.

logRenameCommit(message)

Add a new message to the top of the log.

logToLiveLog(announcement)

setChanged(changed=True)

setLogOutputVerbosity(level)

Repositories

This is the list of repositories from which subuser images may be installed or updated.

class subuserlib.classes.repositories.Repositories(user)

addRepository(repository)

getNewUniqueTempRepoId()

Return a new, unique, identifier for a temporary repository. This function is useful when creating new temporary repositories.

reloadRepositoryLists()

Load the repository list from disk, discarding the current in-memory version.

removeRepository(name)

save()

Save attributes of the repositories to disk.

Note: This is done automatically for you when you commit() the registry.

serializeRepositoriesToDict(repositories)

serializeRepositoryStatesToDict()

serializeToDict()

Note: The save method serializes only that which needs to be saved. Not the entire repositories list. This returns a complete dictionary including system repositories and their states.

A repository is a collection of ImageSource s which are published in a git repo.

class subuserlib.classes.repository.Repository(user, name, gitOriginURI=None, gitCommitHash=None, temporary=False, sourceDir=None)

describe()

getDisplayName()

How should we refer to this repository when communicating with the user?

getFileStructure()

getGitCommitHash()

getGitOriginURI()

getGitRepository()

getImageSourcesDir()

Get the path of the repo’s subuser root on disk on the host.

getName()

getRelativeImageSourcesDir()

Get the path of the repo’s subuser root on disk on the host.

getRepoConfig()

getRepoPath()

Get the path of the repo’s sources on disk.

getSortedList()

Return a list of image sources sorted by name.

getSourceDir()

getURI()

isInUse()

Are there any installed images or subusers from this repository?

isLocal()

isPresent()

Returns True if the repository’s files are present on the system. (Cloned or local)

isTemporary()

loadImageSources()

Load ImageSources from disk into memory.

loadRepoConfig()

Either returns the config as a dictionary or None if no configuration exists or can be parsed.

removeGitRepo()

Remove the downloaded git repo associated with this repository from disk.

serializeToDict()

Return a dictionary which describes the image sources available in this repository.

updateGitCommitHash()

Update the internally stored git commit hash to the current git HEAD of the repository. Returns True if the repository has been updated. Otherwise false.

updateSources(initialUpdate=False)

Pull(or clone) the repo’s ImageSources from git origin.

Images in subuser are built from ImageSource objects.

class subuserlib.classes.imageSource.ImageSource(user, repo, name, explicitConfig=None)

build(parent, useCache=False)

describe()

Describe this ImageSource including it’s default permissions.

Prints to standard output.

getDependency()

Returns the dependency of this ImageSource as a ImageSource. Or None if there is no dependency.

getDockerImageTag()

getHash()

Return the hash of the image directory.

getIdentifier()

Return a standard human readable identifier for an ImageSource.

getImageDir()

getImageFile()

getImageFileContents()

getImageFileType()

getInstalledImages()

Return the installed images which are based on this image.

getLatestInstalledImage()

Get the most up-to-date InstalledImage based on this ImageSource. Returns None if no images have been installed from this ImageSource.

getName()

getPermissions()

getPermissionsFilePath()

getRelativePermissionsFilePath()

getRelativeSourceDir()

getRepository()

Get the repository where this ImageSource resides.

getSourceDir()

getSubusers()

Get a list of subusers that were built from this ImageSource.

Subusers

This is the list of subusers controlled by a given user.

class subuserlib.classes.subusers.Subusers(user)

A subusers object stores the set of all subusers owned by a given user.

getSortedList()

Return a list of subusers sorted by name.

save()

Save the list of subusers to disk.

serializeToDict()

A subuser is an entity that runs within a Docker container and has a home directory and a set of permissions that allow it to access a limited part of the host system.

exception subuserlib.classes.subuser.NoImageSourceException

class subuserlib.classes.subuser.Subuser(user, name, imageId, executableShortcutInstalled, locked, serviceSubusers, imageSource=None, imageSourceName=None, repoName=None, entrypointsExposed=False)

addServiceSubuser(name)

areEntryPointsExposed()

createPermissions(permissionsDict)

describe()

editPermissionsCLI()

exposeEntrypoints()

Create launcher executables for the subuser’s entrypoints.

getDockersideHome()

getHomeDirOnHost()

Returns the path to the subuser’s home dir. Unless the subuser is configured to have a stateless home, in which case returns None.

getImageId()

Get the Id of the Docker image associated with this subuser. None, if the subuser has no installed image yet.

getImageSource()

Note, it is posssible that the subuser’s image source no longer exists, in which case this function raises a NoImageSourceException.

getImageSourceName()

getName()

getPermissions()

getPermissionsDir()

getPermissionsDotJsonWritePath()

getPermissionsTemplate()

getRelativePermissionsDir()

Get the permissions directory as relative to the registry’s git repository.

getRunReadyImage()

getRuntime(environment, extraDockerFlags=None, entrypoint=None)

Returns the subuser’s Runtime object for it’s current permissions, creating it if necessary.

getRuntimeCache()

getServiceSubuserNames()

Get this subuser’s service subusers.

getSourceRepoName()

getX11Bridge()

Return the X11 bridge object for this subuser.

installExecutableShortcut()

installLaunchScript(name, script)

Install a trivial executable script into the PATH which launches the subser image.

isExecutableShortcutInstalled()

isImageInstalled()

loadPermissions()

locked()

Returns True if the subuser is locked. Users lock subusers in order to prevent updates and rollbacks from effecting them.

removePermissions()

Remove the user set and template permission files.

setEntrypointsExposed(exposed)

setExecutableShortcutInstalled(installed)

setImageId(imageId)

Set the installed image associated with this subuser.

setLocked(locked)

Mark the subuser as locked or unlocked.

We lock subusers to their current states to prevent updates and rollbacks from effecting them.

setupHomeDir()

Sets up the subuser’s home dir, along with creating symlinks to shared user dirs.

wereEntryPointsExposedThisRun()

exception subuserlib.classes.subuser.SubuserHasNoPermissionsException

Both Subuser and ImageSource objects have permissions.

Each subuser has a set of permissions which specify what parts of the host system it is allowed to access.

class subuserlib.classes.permissions.Permissions(user, initialPermissions, writePath=None)

applyChanges(permissionsToRemove, permissionsToAddOrChange)

describe()

getHash()

Return the SHA512 hash of the given permissions.

getWritePath()

Return the path to which the permissions object is to be saved.

save()