.\
.\"
.\" Define V font for inline verbatim, using C font in formats
.\" that render this, and otherwise B font.
.ie "\f[CB]x\f[]"x" \{\
. ftr V B
. ftr VI BI
. ftr VB B
. ftr VBI BI
.\}
.el \{\
. ftr V CR
. ftr VI CI
. ftr VB CB
. ftr VBI CBI
.\}
.TH "DISTROBOX-EXPORT" "1" "Dec 2022" "Distrobox" "User Manual"
.hy
.SH NAME
.IP
.nf
\f[C]
distrobox-export
\f[R]
.fi
.SH DESCRIPTION
.PP
\f[B]Application and service exporting\f[R]
.PP
distrobox-export takes care of exporting an app a binary or a service
from the container to the host.
.PP
The exported app will be easily available in your normal launcher and it
will automatically be launched from the container it is exported from.
.SH SYNOPSIS
.PP
\f[B]distrobox-export\f[R]
.IP
.nf
\f[C]
--app/-a:       name of the application to export
--bin/-b:       absolute path of the binary to export
--service/-s:       name of the service to export
--delete/-d:        delete exported application or service
--export-label/-el: label to add to exported application name.
            Defaults to (on \[rs]$container_name)
--export-path/-ep:  path where to export the binary
--extra-flags/-ef:  extra flags to add to the command
--sudo/-S:      specify if the exported item should be run as sudo
--help/-h:      show this message
--verbose/-v:       show more verbosity
--version/-V:       show version
\f[R]
.fi
.PP
You may want to install graphical applications or user services in your
distrobox.
Using \f[V]distrobox-export\f[R] from \f[B]inside\f[R] the container
will let you use them from the host itself.
.SH EXAMPLES
.IP
.nf
\f[C]
distrobox-export --app mpv [--extra-flags \[dq]flags\[dq]] [--delete] [--sudo]
distrobox-export --service syncthing [--extra-flags \[dq]flags\[dq]] [--delete] [--sudo]
distrobox-export --bin /path/to/bin --export-path \[ti]/.local/bin [--extra-flags \[dq]flags\[dq]] [--delete] [--sudo]
\f[R]
.fi
.PP
\f[B]App export example\f[R]
.IP
.nf
\f[C]
distrobox-export --app abiword
\f[R]
.fi
.PP
This tool will simply copy the original \f[V].desktop\f[R] files along
with needed icons, add the prefix
\f[V]/usr/local/bin/distrobox-enter -n distrobox_name -e ...\f[R] to the
commands to run, and save them in your home to be used directly from the
host as a normal app.
.PP
\f[B]Service export example\f[R]
.IP
.nf
\f[C]
distrobox-export --service syncthing --extra-flags \[dq]--allow-newer-config\[dq]
distrobox-export --service nginx --sudo
\f[R]
.fi
.PP
For services, it will similarly export the systemd unit inside the
container to a \f[V]systemctl --user\f[R] service, prefixing the various
\f[V]ExecStart ExecStartPre ExecStartPost ExecReload ExecStop ExecStopPost\f[R]
with the \f[V]distrobox-enter\f[R] command prefix.
.PP
The exported services will be available in the host\[cq]s user\[cq]s
systemd session, so
.IP
.nf
\f[C]
systemctl --user status exported_service_name
\f[R]
.fi
.PP
will show the status of the service exported.
.PP
\f[B]Binary export example\f[R]
.IP
.nf
\f[C]
distrobox-export --bin /usr/bin/code --extra-flags \[dq]--foreground\[dq] --export-path $HOME/.local/bin
\f[R]
.fi
.PP
In the case of exporting binaries, you will have to specify
\f[B]where\f[R] to export it (\f[V]--export-path\f[R]) and the tool will
create a little wrapper script that will \f[V]distrobox-enter -e\f[R]
from the host, the desired binary.
This can be handy with the use of \f[V]direnv\f[R] to have different
versions of the same binary based on your \f[V]env\f[R] or project.
.PP
The exported binaries will be exported in the \[lq]\[en]export-path\[rq]
of choice as a wrapper script that acts naturally both on the host and
in the container.
Note that \[lq]\[en]export-path\[rq] is NOT OPTIONAL, you have to
explicitly set it.
.PP
\f[B]Additional flags\f[R]
.PP
You can specify additional flags to add to the command, for example if
you want to export an electron app, you could add the
\[lq]\[en]foreground\[rq] flag to the command:
.IP
.nf
\f[C]
distrobox-export --app atom --extra-flags \[dq]--foreground\[dq]
distrobox-export --bin /usr/bin/vim --export-path \[ti]/.local/bin --extra-flags \[dq]-p\[dq]
distrobox-export --service syncthing --extra-flags \[dq]-allow-newer-config\[dq]
\f[R]
.fi
.PP
This works for services, binaries, and apps.
Extra flags are only used then the exported app, binary, or service is
used from the host, using them inside the container will not include
them.
.PP
\f[B]Unexport\f[R]
.PP
The option \[lq]\[en]delete\[rq] will un-export an app, binary, or
service.
.IP
.nf
\f[C]
distrobox-export --app atom --delete
distrobox-export --bin /usr/bin/vim --export-path \[ti]/.local/bin --delete
distrobox-export --service syncthing --delete
distrobox-export --service nginx --delete
\f[R]
.fi
.PP
\f[B]Run as root in the container\f[R]
.PP
The option \[lq]\[en]sudo\[rq] will launch the exported item as root
inside the distrobox.
.PP
\f[B]Exporting apps from rootful containers\f[R]
.PP
It is worth noting that, when exporting any item - which includes
graphical apps - from rootful containers (created with
\f[V]distrobox create --root\f[R]), root privileges will be needed every
time the item is launched (in order to enter the rootful container),
which, by default, is done using \f[V]sudo\f[R] (see docs for
\f[V]distrobox-enter\f[R] on how to customize that).
However, for graphical apps in specific, since they launch without a
terminal, the usage of \f[V]sudo\f[R] might, at first, make it
impossible to launch them.
.PP
To fix this without needing to customize the sudo program, one can
define a global \f[V]SUDO_ASKPASS\f[R] environment variable on their
machine, which is a PATH to an executable that is run by \f[V]sudo\f[R]
when no terminal is available (or when it is given the
\f[V]--askpass\f[R] or \f[V]-A\f[R] option), and the output of that
executable to stdout is used as the password input.
The executable is called as many times is needed for authentication as
root to succeed (unless a limit of amount of attempts is reached).
.PP
To do this, pick a program to ask the user for graphical password input.
In this example, we will use \f[V]zenity --password\f[R], which should
be present for GNOME users (and can also be installed in other DEs) -
there are other options, such as
\f[V]kdialog --password \[dq]Message\[dq]\f[R] for KDE users.
.PP
Write the call to the desired program to a script file, for example to
\f[V]/usr/bin/my-password-prompt\f[R] (sample contents below):
.IP
.nf
\f[C]
#!/bin/sh
zenity --password \[dq]Authentication as root is required\[dq]
\f[R]
.fi
.PP
(You may save the script under, for example, \f[V]\[ti]/.local/bin\f[R]
if you want to keep it fully local to your user.)
.PP
Afterwards, make it executable (e.g.\ run
\f[V]sudo chmod +x /usr/bin/my-password-prompt\f[R]).
Then, make sure to set \f[V]SUDO_ASKPASS\f[R] to
\f[V]\[dq]/usr/bin/my-password-prompt\[dq]\f[R] (replace with your
script\[cq]s path) in a global profile file, so that it is picked up by
sudo when running graphical apps (and, therefore, sudo will run the
script you created to ask for a password).
This is done with the shell line
\f[V]export SUDO_ASKPASS=\[dq]/path/to/script/goes/here\[dq]\f[R].
You can do this for your user only by running the command below (replace
the script path as needed):
.IP
.nf
\f[C]
echo \[aq]export SUDO_ASKPASS=\[dq]/usr/bin/my-password-prompt\[dq]\[aq] >> \[ti]/.profile
\f[R]
.fi
.PP
Which appends the appropriate line to the end of your
\f[V]\[ti]/.profile\f[R] file, thus making the change local to your
user.
Alternatively, to set it system-wide (for all users), you may create a
file in \f[V]/etc/profile.d/\f[R] (or equivalent for your system) with
that line.
.PP
Now just log out and log back in, and graphical apps exported from
rootful containers should now be properly asking for root\[cq]s password
before launching (instead of not opening, if that was the case before).
.PP
\f[B]Notes\f[R]
.PP
Note you can use \[en]app OR \[en]bin OR \[en]service but not together.
.IP
.nf
\f[C]
distrobox-export --service nginx --sudo
\f[R]
.fi
.PP
[IMAGE: app-export (https://user-images.githubusercontent.com/598882/144294795-c7785620-bf68-4d1b-b251-1e1f0a32a08d.png)]
.PP
[IMAGE: service-export (https://user-images.githubusercontent.com/598882/144294314-29a8921f-4511-453d-bf8e-d0d1e336db91.png)]
.PP
NOTE: some electron apps such as vscode and atom need additional flags
to work from inside the container, use the \f[V]--extra-flags\f[R]
option to provide a series of flags, for example:
.PP
\f[V]distrobox-export --app atom --extra-flags \[dq]--foreground\[dq]\f[R]