FreeBSD Manual Pages
APPJAIL-X11(1) General Commands Manual APPJAIL-X11(1) NAME appjail-x11 -- Execute x11 applications in jails SYNOPSIS appjail x11 name [options ...] DESCRIPTION The appjail x11 utility is designed to run an x11 application inside the jail with MIT-MAGIC-COOKIE-1 authentication already configured. With this approach, even if the /tmp/.X11-unix directory is shared with other sock- ets, an x11 application inside the jail cannot access other X servers. This utility uses Xephyr(1) as the X server, so you will have the advantage that the window will behave like any other application, but running inside the isolated environment as if it were running on the host. This utility also "refreshes" the server when the main window is resized, so the -resizeable parameter of Xephyr(1) works quite well, providing an experi- ence similar to that of xpra(1). The other advantage of using this utility is that it automatically reserves a free display number, so you don't need to keep track of this, which is not very practical from a human perspective. See "X11 PARAMETERS" in app- jail.conf(5) for details on configuration, but the default settings work well in many cases. This utility is designed not to touch the Xauthority file you specify, so you don't have to worry about messing up your precious authorizations with jails that may even be ephemeral. The cookie is only created if no entry is found in the Xauthority you spec- ify. This cookie is ephemeral, so it is replaced by a new one after the next execution. If you want to use other useful utilities such as xclip(1), you must create an entry in Xauthority for the display used inside the jail. Of course, this is a chicken-egg problem, since you don't know which display to use before it is assigned, so run this utility at least once and the display number will be assigned. See appjail-jail(1) to obtain the dis- play number assigned to the jail, or better yet, use the assign_only op- tion, designed to solve this problem. Optionally, if you have installed x11/xdotool and x11/xseticon, this util- ity changes Xephyr(1)'s window icon to easily identify which x11 applica- tions are isolated from the rest. This does not affect other instances of Xephyr(1) not created by this utility. OPTIONS assign_only This option is designed to just reserve the display for the jail and nothing else, and when this utility finishes running, the display is displayed via stdout. display="display" The main server for painting the Xephyr(1)'s window. you specify, which is supposed to allow access to Xephyr(1). By default, the DISPLAY environment variable is used, and if it is not defined, :0 is used as an alternative. exec_env="name=value" Pass an environment variable to the command executed by exec_start. Can be specified multiple times. exec_start="command [args ...]" Application to be run after starting Xephyr(1). In most cases, this is the window manager or desktop environment. You can run an individual application that is not a window manager, but for certain applications that rely heavily on at least a window manager, you should run your ap- plication with the window manager. The value of this parameter may contain some keywords that have special meaning: - %d <Assigned display> If you want to escape a keyword, use %%, e.g. %%d. exec_user="user" Run the application inside the jail as the specified user. The user must exist inside the jail and have a home directory for xauth(1) to work correctly. xauthority="file" Specify an alternative Xauthority file other than the one specified by the X11_XAUTHORITY parameter in appjail.conf(5). xephyr_args="args ..." Pass any valid parameter for Xephyr(1) and Xserver(1). The only para- meters that are implicitly added are -auth, -name (used to distinguish between multiple instances of Xephyr and set customizations such as the icon) and the display used within the jail. Specifying a parameter such as -ac is undefined. xephyr_user="user" Run Xephyr(1) as another user. For this to work, you must have security/su-exec installed. xrandr_refresh="number" Specify the number of seconds in decimal or an integer to wait before re-running xrandr(1) within the jail. Of course, the jail must have x11/xrandr installed for this to work. If you have x11/xev and x11/xdotool installed on your system, this pa- rameter will be ignored, since appjail-x11 will not perform polling to call xrandr(1). Instead, it will simply call xrandr(1) when the window size changes, which is much more efficient. However, this parameter should be set to a value other than 0 to enable this feature. EXIT STATUS The appjail x11 utility exits 0 on success, and >0 if an error occurs. SEE ALSO Xephyr(1) Xserver(1) xauth(1) Xsecurity(7) AUTHORS JesAos Daniel Colmenares Oviedo <DtxdF@disroot.org> BUGS Please note that if you plan to run an x11 jail, you should also use keepenv in your doas.conf(5) or similar for sudo(8), or at least explicitly set options that depend on environment variables affected by your current environment, such as xauthority, xephyr_user, etc. FreeBSD ports 15.quarterly April 11, 2026 APPJAIL-X11(1)
NAME | SYNOPSIS | DESCRIPTION | OPTIONS | EXIT STATUS | SEE ALSO | AUTHORS | BUGS
Want to link to this manual page? Use this URL:
<https://man.freebsd.org/cgi/man.cgi?query=appjail-x11&sektion=1&manpath=FreeBSD+Ports+15.1.quarterly>