mirror of
https://github.com/89luca89/distrobox.git
synced 2026-08-19 01:14:49 -05:00
Rename project to distrobox
This commit is contained in:
89luca89
@@ -1,75 +1,73 @@
|
||||
# simpler-toolbox
|
||||
|
||||
|
||||
A simplified version of Fedora Toolbox written in Posix Sh
|
||||
# Distrobox
|
||||
|
||||
|
||||
Use any linux distribution inside your terminal.
|
||||
|
||||
|
||||
|
||||
## What it does
|
||||
|
||||
It implements what https://github.com/containers/toolbox does but in a simplified and less-featured way.
|
||||
It implements what https://github.com/containers/toolbox does but in a simplified way using POSIX sh and with broader compatibility.
|
||||
|
||||
All the props goes to them as they had the great idea to implement this stuff.
|
||||
|
||||
## But what is a toolbox?
|
||||
## But what is a distrobox?
|
||||
|
||||
Toolbox is a tool for Linux operating systems, which allows the use of containerized
|
||||
command line environments.
|
||||
Distrobox is a tool for Linux operating systems, which allows the use of containerized command line environments.
|
||||
It is built on top of Podman and other standard container technologies from OCI.
|
||||
|
||||
The intention is to provide a mutable environment on a host where the filesystem is immutable (Like Suse's MicroOS or Fedora Silverblue)
|
||||
The intention is to provide a mutable environment on a host where the filesystem is immutable (like Suse's MicroOS, Fedora Silverblue, Endless OS or SteamOS3)
|
||||
or where the user doesn't have privileges to modify the host (non-sudo users for example)
|
||||
|
||||
So even if you're not a sudoer or your distro doesn't have access to a traditional package manager, you
|
||||
will still be able to perform your `apt/dnf/pacman/pkg/zypper` shenanigans.
|
||||
|
||||
The toolbox environment is based on an OCI image.
|
||||
This image is used to create a toolbox container that seamlessly integrates with the rest of the
|
||||
The distrobox environment is based on an OCI image.
|
||||
This image is used to create a distrobox container that seamlessly integrates with the rest of the
|
||||
operating system by providing access to the user's home directory,
|
||||
the Wayland and X11 sockets, networking (including Avahi),
|
||||
removable devices (like USB sticks), systemd journal, SSH agent, D-Bus,
|
||||
the Wayland and X11 sockets, networking, removable devices (like USB sticks), systemd journal, SSH agent, D-Bus,
|
||||
ulimits, /dev and the udev database, etc..
|
||||
|
||||
# Aims
|
||||
|
||||
This project aims to bring `toolbox` to any distro supporting podman.
|
||||
This project aims to bring any distro userland to any other distro supporting podman.
|
||||
It has been written in posix sh to be as portable as possible and not have problems
|
||||
with glibc compatibility or versions.
|
||||
|
||||
It also aims to enter the container as fast as possible, every millisecond adds up if you use the it
|
||||
as your default environment for your terminal:
|
||||
|
||||
These are some simple results of `toolbox enter` on the same container on my weak laptop:
|
||||
These are some simple results of `distrobox-enter` on the same container on my weak laptop:
|
||||
|
||||
```
|
||||
luca-linux@x250:~$ time toolbox_enter -n fedora-toolbox-35 -- whoami
|
||||
luca-linux@x250:~$ time distrobox-enter -n fedora-distrobox-35 -- whoami
|
||||
luca-linux
|
||||
|
||||
real 0m0.494s
|
||||
user 0m0.135s
|
||||
sys 0m0.070s
|
||||
|
||||
luca-linux@x250:~$ time toolbox_enter -n fedora-toolbox-35 -- whoami
|
||||
luca-linux@x250:~$ time distrobox-enter -n fedora-distrobox-35 -- whoami
|
||||
luca-linux
|
||||
|
||||
real 0m0,302s
|
||||
user 0m0,118s
|
||||
sys 0m0,095s
|
||||
|
||||
luca-linux@x250:~$ time toolbox_enter -n fedora-toolbox-35 -- whoami
|
||||
luca-linux@x250:~$ time distrobox-enter -n fedora-distrobox-35 -- whoami
|
||||
luca-linux
|
||||
|
||||
real 0m0,281s
|
||||
user 0m0,116s
|
||||
sys 0m0,063s
|
||||
```
|
||||
It also includes a `toolbox_export` functionality to export applications and services from
|
||||
It also includes a `distrobox-export` functionality to export applications and services from
|
||||
the container onto the host.
|
||||
|
||||
# Compatibility
|
||||
|
||||
Differently from the original project, this one does **not need** a dedicated image
|
||||
but can use normal images in example from docker hub.
|
||||
This project does **not need** a dedicated image but can use normal images in example from docker hub.
|
||||
|
||||
Granted, they may not be as featureful as expected (some of them do not even have `which` )
|
||||
but that's all doable in the container itself after bootstrapping it.
|
||||
@@ -86,7 +84,7 @@ Host compatibility tested on:
|
||||
- Debian 11
|
||||
- Centos 8 Stream
|
||||
|
||||
Toolbox guests tested with the following container images:
|
||||
distrobox guests tested with the following container images:
|
||||
|
||||
| Distro | Images |
|
||||
| --- | --- |
|
||||
@@ -102,7 +100,7 @@ Toolbox guests tested with the following container images:
|
||||
| Fedora 34 | registry.fedoraproject.org/fedora-toolbox:34, docker.io/library/fedora:34 |
|
||||
| Fedora 35 | registry.fedoraproject.org/fedora-toolbox:35, docker.io/library/fedora:35 |
|
||||
| Opensuse Leap | registry.opensuse.org/opensuse/leap:latest |
|
||||
| Opensuse Tumbleweed | registry.opensuse.org/opensuse/thumbleweed:latest, registry.opensuse.org/opensuse/toolbox:latest |
|
||||
| Opensuse Tumbleweed | registry.opensuse.org/opensuse/tumbleweed:latest, registry.opensuse.org/opensuse/toolbox:latest |
|
||||
| Oracle Linux 7 | container-registry.oracle.com/os/oraclelinux:7 |
|
||||
| Oracle Linux 8 | container-registry.oracle.com/os/oraclelinux:8 |
|
||||
| Rocky Linux 8 | docker.io/rockylinux/rockylinux:8 |
|
||||
@@ -111,29 +109,31 @@ Toolbox guests tested with the following container images:
|
||||
| Ubuntu 21.10 | docker.io/library/ubuntu:21.10 |
|
||||
|
||||
|
||||
Note however that if you use a non-toolbox pre configured image, the **first** `toolbox_enter` (or to be more precise the `podman start`) you perform
|
||||
Note however that if you use a non-toolbox pre configured image (e.g. images pre-baked to work with https://github.com/containers/toolbox),
|
||||
the **first** `distrobox-enter` (or to be more precise the `podman start`) you perform
|
||||
will take a while as it will install with the pkg manager the missing dependencies.
|
||||
|
||||
A small time-tax to pay for the ability to use any type of image.
|
||||
This will **not** occur after the first time, and will enter directly.
|
||||
|
||||
# Usage
|
||||
|
||||
### Create the toolbox
|
||||
### Create the distrobox
|
||||
|
||||
toolbox_create --image registry.fedoraproject.org/fedora-toolbox:35 --name fedora-toolbox-35
|
||||
distrobox-create --image registry.fedoraproject.org/fedora:35 --name fedora-35
|
||||
|
||||
Arguments:
|
||||
--image/-i: image to use for the container default: registry.fedoraproject.org/fedora-toolbox:35
|
||||
--name/-n: name for the toolbox default: fedora-toolbox-35
|
||||
--name/-n: name for the distrobox default: fedora-toolbox-35
|
||||
--help/-h: show this message
|
||||
-v: show more verbosity
|
||||
|
||||
If the image is not present you'll be prompted to `podman pull` it.
|
||||
|
||||
### Init the toolbox
|
||||
### Init the distrobox
|
||||
|
||||
|
||||
toolbox_init --name test-user --user 1000 --group 1000 --home /home/test-user
|
||||
distrobox-init --name test-user --user 1000 --group 1000 --home /home/test-user
|
||||
|
||||
Arguments:
|
||||
--name/-n: user name
|
||||
@@ -146,22 +146,22 @@ If the image is not present you'll be prompted to `podman pull` it.
|
||||
This is used as entrypoint for the created container, it will take care of creating the users,
|
||||
setting up sudo, mountpoints and exports.
|
||||
|
||||
### Enter the toolbox
|
||||
### Enter the distrobox
|
||||
|
||||
toolbox_enter --name fedora-toolbox-35 -- bash -l
|
||||
distrobox-enter --name fedora-35 -- bash -l
|
||||
|
||||
Arguments:
|
||||
--name/-n: name for the toolbox default: fedora-toolbox-35
|
||||
--name/-n: name for the distrobox default: fedora-35
|
||||
--: end arguments execute the rest as command to execute at login default: bash -l
|
||||
--help/-h: show this message
|
||||
-v: show more verbosity
|
||||
|
||||
This is used to enter the toolbox itself, personally I just create multiple profiles in my `gnome-terminal` to have multiple distros accessible.
|
||||
This is used to enter the distrobox itself, personally I just create multiple profiles in my `gnome-terminal` to have multiple distros accessible.
|
||||
|
||||
# Application and service exporting
|
||||
|
||||
toolbox_export --app mpv
|
||||
toolbox_export --service syncthing
|
||||
distrobox-export --app mpv
|
||||
distrobox-export --service syncthing
|
||||
|
||||
Note you can use --app OR --service but not together.
|
||||
|
||||
@@ -172,28 +172,26 @@ This is used to enter the toolbox itself, personally I just create multiple prof
|
||||
--help/-h: show this message
|
||||
-v: show more verbosity
|
||||
|
||||
You may want to install graphical applications or user services in your toolbox.
|
||||
Using `toolbox_eport` from **inside** the container, will let you use them from the host itself.
|
||||
You may want to install graphical applications or user services in your distrobox.
|
||||
Using `distrobox-eport` from **inside** the container, will let you use them from the host itself.
|
||||
|
||||
Examples:
|
||||
|
||||
`toolbox_export --app abiword`
|
||||
`distrobox-export --app abiword`
|
||||
|
||||
`toolbox_export --service syncthing`
|
||||
`distrobox-export --service syncthing`
|
||||
|
||||
This tool will simply copy the original `.desktop` files (with needed icons) or `.service` files,
|
||||
add the prefix `/usr/local/bin/toolbox_enter -n fedora-toolbox -e ... ` to the commands to run, and
|
||||
add the prefix `/usr/local/bin/distrobox-enter -n fedora-35 -e ... ` to the commands to run, and
|
||||
save them in your home to be used directly from the host as a normal app or `systemctl --user` service.
|
||||
|
||||
|
||||
|
||||
|
||||
|
||||
|
||||
|
||||
|
||||
|
||||
# Installation
|
||||
|
||||
place the three files somewhere in your $PATH.
|
||||
Clone the project using `git clone` or using the `download` button above to get the zip file.
|
||||
Enter the folder an copy the script files anywhere in your `$PATH`, remember to mark them as executable.
|
||||
|
||||
# Dependencies
|
||||
|
||||
|
||||
@@ -19,8 +19,8 @@ container_user_gid="$(id -rg)"
|
||||
container_user_home="${HOME}"
|
||||
container_user_name="${USER}"
|
||||
container_user_uid="$(id -ru)"
|
||||
toolbox_entrypoint_path="$(command -v toolbox_init)"
|
||||
toolbox_export_path="$(command -v toolbox_export)"
|
||||
distrobox_entrypoint_path="$(command -v distrobox-init)"
|
||||
distrobox_export_path="$(command -v distrobox-export)"
|
||||
verbose=0
|
||||
|
||||
# Print usage to stdout.
|
||||
@@ -30,11 +30,11 @@ verbose=0
|
||||
# print usage with examples.
|
||||
show_help() {
|
||||
echo "USAGE:
|
||||
toolbox_create --image registry.fedoraproject.org/fedora-toolbox:35 --name fedora-toolbox-35
|
||||
distrobox-create --image registry.fedoraproject.org/fedora-toolbox:35 --name fedora-toolbox-35
|
||||
|
||||
Arguments:
|
||||
--image/-i: image to use for the container default: registry.fedoraproject.org/fedora-toolbox:35
|
||||
--name/-n: name for the toolbox default: fedora-toolbox-35
|
||||
--name/-n: name for the distrobox default: fedora-toolbox-35
|
||||
--help/-h: show this message
|
||||
-v: show more verbosity
|
||||
"
|
||||
@@ -86,7 +86,7 @@ fi
|
||||
# Arguments:
|
||||
# None
|
||||
# Outputs:
|
||||
# prints the podman command to create the toolbox container
|
||||
# prints the podman command to create the distrobox container
|
||||
generate_command() {
|
||||
# Set the container hostname the same as the container name.
|
||||
# use the host's namespace for ipc, network, pid, ulimit
|
||||
@@ -102,7 +102,7 @@ generate_command() {
|
||||
# we also mount host's root filesystem to /run/host, to be
|
||||
# able to syphon dynamic configurations from the host
|
||||
#
|
||||
# also mount the toolbox_init utility as the container entrypoint
|
||||
# also mount the distrobox-init utility as the container entrypoint
|
||||
echo "--name ${container_name}
|
||||
--env=SHELL=${SHELL}
|
||||
--network host
|
||||
@@ -113,10 +113,10 @@ generate_command() {
|
||||
--ulimit host
|
||||
--user root:root
|
||||
--userns keep-id
|
||||
--volume ${toolbox_entrypoint_path}:/usr/bin/entrypoint:ro"
|
||||
# let's check if we can include toolbox_export or not
|
||||
if [ -n "${toolbox_export_path}" ]; then
|
||||
echo "--volume ${toolbox_export_path}:/usr/bin/toolbox_export:ro"
|
||||
--volume ${distrobox_entrypoint_path}:/usr/bin/entrypoint:ro"
|
||||
# let's check if we can include distrobox-export or not
|
||||
if [ -n "${distrobox_export_path}" ]; then
|
||||
echo "--volume ${distrobox_export_path}:/usr/bin/distrobox-export:ro"
|
||||
fi
|
||||
echo "--volume ${container_user_home}:${container_user_home}:rslave
|
||||
--volume /:/run/host:rslave
|
||||
@@ -142,7 +142,7 @@ generate_command() {
|
||||
for socket in $(find /run -iname "*socket" ! -path "/run/user/*" 2>/dev/null); do
|
||||
echo "--volume ${socket}:${socket}"
|
||||
done
|
||||
# now execute the entrypoint, refer to `toolbox_init -h` for instructions
|
||||
# now execute the entrypoint, refer to `distrobox-init -h` for instructions
|
||||
echo "${container_image}
|
||||
/usr/bin/entrypoint -v --name ${container_user_name}
|
||||
--user ${container_user_uid} --group ${container_user_gid}
|
||||
@@ -25,10 +25,10 @@ container_command="${SHELL} -l"
|
||||
# print usage with examples.
|
||||
show_help() {
|
||||
echo "USAGE:
|
||||
toolbox_enter --name fedora-toolbox-35 -- bash -l
|
||||
distrobox-enter --name fedora-toolbox-35 -- bash -l
|
||||
|
||||
Arguments:
|
||||
--name/-n: name for the toolbox default: fedora-toolbox-35
|
||||
--name/-n: name for the distrobox default: fedora-toolbox-35
|
||||
--: end arguments execute the rest as command to execute at login default: bash -l
|
||||
--help/-h: show this message
|
||||
-v: show more verbosity
|
||||
@@ -75,7 +75,7 @@ fi
|
||||
# Arguments:
|
||||
# None
|
||||
# Outputs:
|
||||
# prints the podman command to enter the toolbox container
|
||||
# prints the podman command to enter the distrobox container
|
||||
generate_command() {
|
||||
# If the container is not already running, we need to start if first
|
||||
if ! podman ps | grep -q "${container_name}$"; then
|
||||
@@ -88,7 +88,7 @@ generate_command() {
|
||||
echo "Cannot start container, does it exist?" 1>&2
|
||||
echo "Try running first:" 1>&2
|
||||
echo "" 1>&2
|
||||
echo " toolbox_create --name <name-of-container> --image <remote>/<docker>:<tag>" 1>&2
|
||||
echo " distrobox-create --name <name-of-container> --image <remote>/<docker>:<tag>" 1>&2
|
||||
exit 1
|
||||
else
|
||||
echo >&2 "Starting container"
|
||||
@@ -104,7 +104,7 @@ generate_command() {
|
||||
|
||||
# entering container using our user and workdir
|
||||
echo "podman exec --interactive --tty --user=${USER} --workdir=${HOME}"
|
||||
echo "--env=TOOLBOX_HOST_PATH=$(command -v toolbox_enter)"
|
||||
echo "--env=DISTROBOX_ENTER_PATH=$(command -v distrobox-enter)"
|
||||
# exporting current environment to container
|
||||
for i in $(printenv | grep '=' | head -n -2); do
|
||||
echo "--env=$i"
|
||||
@@ -3,7 +3,7 @@
|
||||
# Expected env variables:
|
||||
# HOME
|
||||
# USER
|
||||
# TOOLBOX_HOST_PATH
|
||||
# DISTROBOX_ENTER_PATH
|
||||
|
||||
trap '[ "$?" -ne 0 ] && echo An error occurred' EXIT
|
||||
|
||||
@@ -28,8 +28,8 @@ done
|
||||
# print usage with examples.
|
||||
show_help() {
|
||||
echo "USAGE:
|
||||
toolbox_export --app mpv
|
||||
toolbox_export --service syncthing
|
||||
distrobox-export --app mpv
|
||||
distrobox-export --service syncthing
|
||||
|
||||
Note you can use --app OR --service but not together.
|
||||
|
||||
@@ -102,7 +102,7 @@ fi
|
||||
|
||||
container_name=$(grep "name=" /run/.containerenv | cut -d'"' -f2)
|
||||
# Prefix to add to an existing command to work throught the container
|
||||
container_command_prefix="${TOOLBOX_HOST_PATH} --name ${container_name} -e "
|
||||
container_command_prefix="${DISTROBOX_ENTER_PATH} --name ${container_name} -e "
|
||||
|
||||
# Work on a desktop app export
|
||||
if [ -n "${container_app}" ]; then
|
||||
@@ -112,7 +112,7 @@ if [ -n "${container_app}" ]; then
|
||||
exit 127
|
||||
fi
|
||||
# Find desktop file for the application to export
|
||||
desktop_files=$(grep -ril "${container_app}" /usr/share/applications)
|
||||
desktop_files=$(grep -ril "${container_app}" /usr/share/applications/*)
|
||||
icon_files=$(find /usr/share/icons -iname "*${container_app}*")
|
||||
|
||||
# copy icons in home directory
|
||||
@@ -130,7 +130,7 @@ if [ -n "${container_app}" ]; then
|
||||
fi
|
||||
done
|
||||
|
||||
# create desktop files for the toolbox
|
||||
# create desktop files for the distrobox
|
||||
for desktop_file in $desktop_files; do
|
||||
desktop_home_file="$(basename "${desktop_file}")"
|
||||
|
||||
@@ -139,7 +139,7 @@ if [ -n "${container_app}" ]; then
|
||||
rm -f "${HOME}/.local/share/applications/${desktop_home_file}"
|
||||
else
|
||||
# If a TryExec is present, we have to fake it as it will not work throught the
|
||||
# toolbox separation
|
||||
# container separation
|
||||
sed "s|^Exec=|Exec=${container_command_prefix} |g" "${desktop_file}" |
|
||||
sed "s|^TryExec=.*|TryExec=true|g" \
|
||||
>"${HOME}/.local/share/applications/${desktop_home_file}"
|
||||
@@ -16,7 +16,7 @@ verbose=0
|
||||
# print usage with examples.
|
||||
show_help() {
|
||||
echo "USAGE:
|
||||
toolbox_init --name $USER --user $(id -ru) --group $(id -rg) --home $HOME
|
||||
distrobox-init --name $USER --user $(id -ru) --group $(id -rg) --home $HOME
|
||||
|
||||
Arguments:
|
||||
--name/-n: user name
|
||||
Binary file not shown.
|
After Width: | Height: | Size: 2.9 MiB |
Binary file not shown.
|
After Width: | Height: | Size: 188 KiB |
Binary file not shown.
|
After Width: | Height: | Size: 3.8 MiB |
Binary file not shown.
|
After Width: | Height: | Size: 72 KiB |
Reference in New Issue
Block a user