Advanced uses
Exegol home directory
The ~/.exegol folder exists in the user’s home folder to centralize “exegol resources”, “my-resources”, volumes and also the configuration file.
The configuration file (YAML) is located at
~/.exegol/config.ymland is generated by the wrapper during the first execution, with the default configurations.By default, every exegol container has a workspace volume. If the path of this volume is not specified by the user (see start parameters), a folder with the name of the container will be created in the “private workspace” folder. By default, this folder is located at
~/.exegol/workspaces/.
Exegol configuration
The Exegol wrapper is configured with many default settings. Most of them can be modified with a simple argument. For productivity purposes, setting a different default behavior once and not have to add the same options everytime is interesting. For this exact purpose, a configuration file exists that allows users to persistently change the behavior and operations to be performed by default.
The user configuration currently in place can be viewed with the command: exegol info -v. More information on the info page.
Within the ~/.exegol/config.yml file, several settings can be configured to customize the Exegol experience, all distributed in multiple sections below.
The volume section allows to change the default path for various volumes.
Warning
Volume path can be changed at any time but already existing containers will not be affected by the update and will keep the original paths they were created with.
my_resources_path: the “my-resources” volume is a storage space dedicated to the user to customize his environment and tools. This volume is, by default, shared across all exegol containers. See details about it.exegol_resources_path: exegol-resources are data and static tools downloaded in addition to docker images. These tools are complementary and are accessible directly from the host. See details.private_workspace_path: when containers do not have an explicitly declared workspace at their creation (i.e. with--cwd-mount, or--workspace), a dedicated folder will be created at this location to share the workspace with the host but also to save the data after deleting the container.
The config section allows you to modify the default behavior of the Exegol wrapper.
auto_check_update: enables automatic check for wrapper update. (Default:True)auto_remove_image: automatically remove outdated image when they are no longer used. (Default:True)auto_update_workspace_fs: automatically modifies the permissions of folders and sub-folders in your workspace by default to enable file sharing between the container with your host user. (Default:False)default_start_shell: default shell command to start. (Default:zsh)enable_exegol_resources: Enables or not the exegol resources module by default on any new container. (Default:True)
Change the configuration of the shell logging functionality.
logging_method: Choice of the method used to record the sessions,scriptorasciinema. (Default:asciinema)enable_log_compression: Enable automatic compression of log files (with gzip). (Default:True)
Change the configuration of the virtual Desktop feature.
enabled_by_default: Enables or not the desktop mode by default. If this attribute is set to True, then using the CLI--desktopoption will be inverted and will DISABLE the feature (Default:False)default_protocol: Default desktop protocol,can behttp, orvncdepending on your wrapper / image version. (Default:http)localhost_by_default: Desktop service is exposed on localhost by default. If set to true, services will be exposed onlocalhost(127.0.0.1) otherwise it will be exposed on0.0.0.0. This setting can be overwritten with –desktop-config. (Default:True)
My-resources
“My-resources” is a major feature allowing Exegol users to have a volume, shared with all Exegol containers, that can centralize their own resources and configurations. It allows users to enjoy their own tools that are not available in Exegol but also to customize their Exegol setup. More information on the dedicated documentation page My-Resources.
This volume is accessible from the host at ~/.exegol/my-resources/ and from the containers (if the feature was left enabled at the container creation) at /opt/my-resources.
To facilitate its use, a read/write access system shared (between the host user and the container root user) has been implemented.
Hint
To allow this permissions sharing, the “my-resources” folder (and all subdirectories) must have the Set-GID permission bit set. This is done automatically by the wrapper if the current user has sufficient rights. Otherwise, the wrapper will display a sudo command to be executed manually to update the relevant permissions.
The host path of this volume can be changed from the configuration file ~/.exegol/config.yml.
Warning
Be careful not to use a folder with existing data, in which case their permissions will be automatically modified to enable access sharing.
This change will not be applied to already existing exegol containers.
Local builds
When installing Exegol, while downloading the pre-built and compressed Docker images from Dockerhub is advised, users can build their own images locally. The wrapper has a local build feature to create and manage local exegol images.
The exegol install command can be used for that purpose. The user must specify an image name that does not match one of the remote images available from dockerhub. The wrapper will suggest to build a local image with this name. If the user chooses to build an image locally, he will then have to choose a build profile among those available. The build profile is merely the dockerfile to follow during the build process. An arbitrary dockerfile can be added in /path/to/Exegol/exegol-docker-build/name.dockerfile.
Tip
the
-vparameter can be added to have more details about the build process.the detailed logs of the docker build process can also be saved in a file with the
--build-logparameter.