Sign Up
Log In
Log In
or
Sign Up
Places
All Projects
Status Monitor
Collapse sidebar
home:estellnb:elstel
xchroot
xchroot.8
Overview
Repositories
Revisions
Requests
Users
Attributes
Meta
File xchroot.8 of Package xchroot
.TH XCHROOT 8 "August 2013" "version 2.3" "Maintenance Commands" .SH NAME xchroot \- chroot for Xorg/X11 with unionfs/aufs support .SH SYNOPSIS .BI "xchroot " "[OPTIONS] ROOTDIR [COMMANDS] [--env ENVVAR] [--noask]" .br .BI "xchroot " "[OPTIONS] COMMAND-INSIDE-SUDOERS-ROOTDIR [--env ENVVAR] [--noask]" .br .BI "xchroot " "[OPTIONS] " "cleanup " "ROOTDIR " .br .BI "xchroot showmount " "ROOTDIR " .br .br .BI "xchroot " "[OPTIONS] " "escape " "[COMMANDS] [--env ENVVAR] [--noask]" .br .BI "xchroot " "-t ROOTDIR [COMMANDS] -- OPTIONS" .br .BI "xchroot " "-t " "escape " "[COMMANDS] -- OPTIONS" .br .BI "xchroot " "[--dir xy/--dirpfx xy] [-u fromuser] " "add/delsudoers " "USER1 USER2 ... " .br .BI "xchroot " "--escape [-u fromuser] " "add/delsudoers " "USER1 USER2 ... " .br .B xchroot listsudoers / listrunmounts / list-desktop-categories .br .B xchroot ppids / xchppids .SH DESCRIPTION xchroot is a little convenience bash script that will allow you to run X-based applications and programs with additional audio support in a chroot environment. It has a lot of options like automatic mount mirroring and GUI desktop menu item creation for chrooted applications. Provisions are also taken that you can escape a chroot back to the original root. You may also chroot to a new environment without thouching any of its files either by using aufs or unionfs. You may backup your temporary changes on exit and kill of xchroot as squashfs incrementally and restore them. The additional management commands allow you to xchroot as user via sudo. .SH OPTIONS .TP 22 .B --license / -l show license information. .TP .B --help short summary of this man page .TP .B --alldisplays do not solely forward $DISPLAY to the chroot environment \fI(currently used for extraction of Xauthority information but not for --socat.)\fP .TP .BI --user/-u " user[:group]" chown to user[:group] after chrooting. .TP .B --norc do not execute /etc/bash.bashrc and run bash with --norc .TP .BI --shell " exec" use \fIexec\fR instead of the default shell in /etc/passwd .TP .BI "--env " var=value same as \fIenv var=value xchroot ...\fR; used only for certain environment variables with sudo: This is useful for making environment variables survive in sudoer entries where any globbing before the reference to the xchroot executable would be lethal thus allowing the execution of any program as root instead. Note that the --env option can be given at the end of the command line string after \fICOMMANDS\fR even without a preceding '--'. .TP .B --approved list all vars that can be used with the --env option separated by spaces. The only allowed variables for sudo trespassing are at the current state $XCHROOT_MYROOT, $XAUTHORITY and $DISPLAY. These variables are crucial for the functionality provided by xchroot. .TP .B --verbose / -v / -vv be more verbose, \fI-vv\fR: show all mounted mount points .TP .B --quiet / -q be quiet .TP .B --noask no user interaction; batch mode: do not ask for termination of processes still running in the chroot environment after exit; do not ask to save changes to image after an xchroot --aufs/--unionfs .TP .B --no-audio do not mount /run/user/XXX/pulse for pulseaudio support .TP .BI --on " runmounts / " --off " runmounts" Switch on/off mounting of these mount points separated by a colon under /run. \fB"listrunmounts"\fR without \fI--on\fR or \fI--off\fR gives the default mount points under /run. "sess" is special and stands for launching a dbus user session for the specified user in the target chroot. Dbus sessions are not exported to the chroot environment but launched there anew for every user \fI(/run/$UID/bus)\fR. They are used by many desktop programs and required when starting a new X-session. "nwm" is also special and stands for NetworkManager. "udev" may be required for starting an own X-server in the chroot. "mirrtmp" means to mirror \fI/tmp\fR and \fI/var/tmp\fR rather than creating a clean tmpfs there. This may be less secure than the standard option "tmp" since xchroot creates configuration and Xauthority files under \fI/tmp/xchroot\fR which may be readable by the same user of another root. .TP .B --genuine-retval keep return value of chroot which is the return value of the program last executed in the chroot environment instead of generating an own xchroot return value .TP .B --fast be more fast at mounting and umounting: skip /sys/fs/* .TP .B --preserve-env / --keep-env / -i, --no-preserve-env / --no-keep-env / -I Keep all environment variables. Note that the content of some environment variables may no more be valid inside a chroot. This is definitely not recommended if you switch the user as quite a lot of environment variables are user specific. Yet untested feature; work in progress! .SS Xorg connection (for graphical apps): .TP .B --socat/-s most "secure" (note that chroot is not a security feature under Linux in contrast to the FreeBSD jails and that even FreeBSD chails can not secure the X server) .TP .B --mntmp The default for connecting to the X-server. Mounts /tmp/.X11-unix explicitly if /tmp and /var/tmp are not mounted anyway. The latter can be achieved by --on mirrtmp. This was the default for long (and temporarily also is for v2.7.4). .TP .B --noX do not take any provisions for running Xorg/X11 based apps; take care yourself if X access should remain disabled: f.i. do not mount the home directory as there may reside a ~/.Xauthority file .SS mount mirroring \fR(launches background process that keeps mount of different roots in sync) .TP .B --mirror/--mirror-in/-m \fR[dirs]\fB, -n, -w mirror mounts from outside into the root. State directories separated with ':'. If no directories are stated "/media:/home:/mnt" is assumed as parameter. Do not forget to terminate the options with -- if no parameter is given. -n is like -m but it can not have parameters and it needs no terminating -- for the options. -w is the same as -n with a default of "/media:/mnt" .TP .B --mirror-out \fR[dirs] mirror mounts created inside the root out of the root. With or without parameters (-- may be needed). Default is "/media:/mnt". .TP .B --mirror-bidi/-b \fR[dirs] keep mounts synchronized in both directions with the respective defaults for mirror-in and mirror-out. .TP .B --once/-o \fR[dirs]\fB, -p, -d mirror mounts from outside into the root but only once on startup; no background process is needed. -p is like -o but does not allow parameters. ditto for -d but its default is just "/media:/mnt". .SS umounting on exit: .TP .B --noumount / -z do not umount anything; do not terminate running processes, further chroots possible .TP .B --stdumount umount /media, /dev, /sys/, /proc, /selinux .TP .B --umountall umount all under root including root (everything in /etc/fstab is automounted on startup; mount points containing spaces are not supported yet.) .SS aufs and unionfs: .TP .B --aufs (-a) / --unionfs do not change any files or directories inside root; make all changes temporary via unionfs/aufs .TP .B --udba " none/reval/notify" aufs option; whether to propagate changes from the underlying root filesystem; \fI'reval'\fR is the default and test only for the existence of previously existing files; it does not detect the creation of files; \fI'none'\fR may speed up real read only roots though it can cause hangs otherwise and \fI'notify'\fR is slower but required if changes to the underlying root file system should be immediately reflected in the aufs mount. The same rules may apply for manual changes to the files aufs caches internally at /tmp/xchroot/aufs-$rootname-$$. .TP .BI --unionopts " ... \fR/ " --squashopts " ..." specify additional unionfs/aufs/squashfs options (take caution with squashfs-opts; not tested until trying to save image) .TP .BI --maxfiles " N" set max-usable filedescriptors in root to N for union/aufs (default 32768, currently sufficient for KDE) .TP .BI --save " xy-aufs/unionfs.squashfs \fR/ " --restore " xy-aufs/unionfs.squashfs" save/restore changes to unionfs-environment .SH ADDITIONAL COMMANDS .TP .B escape Go back to initial root filesystem unless this was excluded by \fI--no-escape/-E\fR. This filesystem becomes visible under /dev/fd/89. .TP .BI "showmount " ROOT show partitions currently mounted under root .TP .B cleanup If you have killed a chroot, executed it with --noask or chosen to leave programs running or partitions mounted on exit of chroot you may want to perform a cleanup later on; note: xchroot stores temporary files in /tmp/xchroot. .TP .BI "addsudoers: xchroot " "[--dir xy/--dirpfx xy] [-u fromuser] " "addsudoers " "USER1 USER2 ... " Allow \fIfromuser\fR to xchroot to \fIUSER1, USER2, ...\fR. The target directory needs either to be \fIxy (--dir)\fR or to have \fIxy\fR as a praefix \fI(--dirpfx)\fR. If the praefix is not terminated with a slash for \fI--dirpfx\fR then the last directory name is wildcarded. Note that adding group sudoer entries is not supported yet. If \fIfromuser\fR is left out then source and target user are assumed to be the same. Adds entries twice unless they are deleted before adding; see also: listsudoers. .TP .BI "addsudoers: xchroot " "--escape [-u fromuser] " "add/delsudoers " "USER1 USER2 ... " Enable/disable xchroot escaping as user. Adds the closefrom_override default allowing to keep file descriptors open with sudo -C into /etc/sudoers if necessary but never removes it. Execute this in the chroot environment you wanna escape from. .TP .BI "delsudoers: xchroot " "[--dir xy/--dirpfx xy] [-u fromuser] " "delsudoers " "USER1 USER2 ... " Works the same way as addsudoers rather deleting sudoer entries. You may specify \fI"all"\fR either to \fIfromuser\fR or to \fIUSER1, USER2, etc.\fR. .TP .B listsudoers List all sudoer entries for xchroot. .TP .B inst-root-sudo To be executed once on installation of xchroot if your system is not configured to allow sudo from root to any other user by default. .TP .B ppids / xchppids List all parent processes / all xchroot parent processes and say whether they belong to escapable chroots. This could be used for a future extension to escape out of multiple chroots in one step. Also you can see the parent pids that belong to a respective /tmp/xchroot/startup-$$. .TP .B bashrclines deprecated: You may still source this directly via "source <(xchroot bashrclines)" or add the output to your .bashrc: It installs the openroot macro that is no more needed since you can now directly xchroot as user. .P .BI createstartup " --desktop [--category AddCat1;AddCat2;] [--no-which] [--keep-home]" \fR " /dst/chroot/usr/share/applications/application.desktop" .br .BI createstartup " --desktop [--category AddCat1;AddCat2;] [--no-which] [--keep-home]" \fR " escape [/dev/fd/89]/usr/share/applications/application.desktop" .IP Creates a desktop file in the host root for a desktop file in the chroot environment. The desktop file will be used to run the application directly via the click start menu of the GUI as well as indirectly via the file association to run dependent data files with. For \fI/dst/buster/usr/share/applications/xine.desktop\fR a file named \fI/usr/share/applications/xine-buster.desktop\fR will be created. If \fI--no-which\fR is given and the executable has no absolute path specifier, no absolute path specifier is searched for at conversion. The program is run with a bash shell and the default paths instead. If root is not a sudoers entry then search from / downwards for a chroot environment. Give an absolute path, if possible. Other directories for .desktop files are \fI~/.local/share/applications/wine/\fR and \fI/usr/share/xsessions/\fR. .desktop-files under /home are normally put into /usr/share/applications, except if \fI--keep-home\fR is specified. .P .BI createstartup " --command --category Education;GTK;XFCE;" \fR " /dst/chroot/usr/bin/wine /srv/PCintern/mviewer2.exe /srv/PCintern/intern.mvb" .br .BI createstartup " --command --category Education;GTK;XFCE;" \fR " escape [/dev/fd/89]/usr/bin/wine /srv/PCintern/mviewer2.exe /srv/PCintern/intern.mvb" .IP Create a desktop file directly from an executable in a chroot environment. Any desired number of parameters may be passed additionally. The program will be found under the specified categories in the GUI menu, which are separated by a semicolon. For the wine and mviewer2 executables the desktop file name is taken from intern.mvb. This behaviour may be extended to other binaries than wine and mviewer2 in the sources of xchroot. The desktop file will be found in /usr/share/applications for manual editing, f.i. to set an icon. If root is not a sudoers entry then search from / downwards for a chroot environment. Give an absolute path, if possible. .TP .B list-desktop-categories List all categories for the GUI menu that are currently in use. This command is in support for \fBcreatestartup\fI --category\fR .TP .B listrunmounts List all mounts under /run which are turned on by --on or by default and which are not turned --off. "sess" is special and stands for a dbus session rather than a mount point. .TP Note: all other addtional commands are for user management (see for the XCHROOT AS USER and the EXAMPLES section.). .SH ENVIRONMENT VARIABLES .TP $DISPLAY, $XAUTHORITY will be exported to the chroot environment (usually already set for X-clients) .TP $XCONNECT one of the values 'socat', 'mntmp' or 'noX'; note: 'noX' will be ignored if either $DISPLAY or $XAUTHORITY are set; you may use a default value here to prevent warnings when no X server is running like under the rescue console; note that xchroot will never prevent from connecting to the X server as --noX was not ment as security feature. .TP $XCHROOT_MYROOT environment variable defined inside xchroot to determine own root relative to the initial systems root; gets concatenated for multiple recursive xchroots if the environment variable is never deleted (see the --env option) .TP $XCHROOT_NAME short name for current chroot as usable in the PS1 prompt to quickly see in which root we are; also used along with the PID for better distinction of temporary files belonging to an xchroot-environment in /tmp/xchroot; at the moment just the last path component i.e. the basename of $XCHROOT_MYROOT .TP $XCHROOT_USER, $XCHROOT_GROUP what has been specified with the \fI-u user:group\fR argument .TP $XCHROOT_ESCAPED=1 set when an xchroot escape was issued .SH XCHROOT AS USER xchroot can be used to chroot as user (note that chrooting to an infected target root can compromise your system.); i.e. you will be able to remain the same user before and after xchroot. Retrieve a wrapper script called \fBopenroot\fR to xchroot as user by \fBxchroot bashrclines\fR and append that to your >>~/.bashrc. You may use the management commands \fBaddsudoers\fR, \fBdelsudoers\fR and \fBlistsudoers\fR to add entries for openroot into your /etc/sudoers file (see for the SYNOPSIS & EXAMPLES section). .br .br Note that all options except the user option can be used as \fIhead\fR or \fItail options\fR which means that they are either put in front of the chroot directory and command or after a \fB--\fR at the end. The effect of the options will remain the same; however this is a security feature in order to be able to make use of wildcarding in /etc/sudoers so that the target root praefix and the target user can not be wildcarded (-u option only allowed as front option); i.e. use only tail options with openroot putting a -t in front to allow openroot to sudo without password. .SH EXAMPLES \fBxchroot /dst/debian/\fP .br \fBxchroot -m -- /dst/debian/\fP .br \fBxchroot --aufs /dst/debian/\fP .br \fBxchroot --aufs cleanup /dst/debian\fP .br \fBxchroot --noask -q -u elm /dst/debian/ ls \\\fB~\fP .br .TP 10 as user: \fBsudo xchroot --dirpfx /dst/ addsudoers $USER\fP .br \fBxchroot /dst/debchroot/\fP .br \fBxchroot /dst/debchroot/bin/hostname\fP .br \fBxchroot -t /dst/debchroot/ -- --norc --unionfs\fP .SH RETURN VALUES \ \ \ 2xx ... error codes 1xx ... xchroot was executed with success; status about chroot-environment indicated by return value .br 200 ~ EPERM (not run as root) 221 ~ helper program i.e. unionfs/aufs/socat not found, 222 ~ aufs/unionfs --save file already exits, 223 ~ mkdir error 228 ~ target dir is not a chroot environment 253 ~ ENOENT a component in path does not exist 254 ~ ENOTFOUND file not found (--restore image) 255 ~ EINVAL (wrong parameters), .br 132 ~ other xchroot instances still running 100 ~ processes left running in the previous chroot (no other xchroot instances running) .br +1 ~ umounting error because of user, +2 ~ umounting error by xchroot, +4 file deletion/rmdir error +8 ~ possible error at freezing changes (auplink: concerning hard links) +16 ~ rescuable changes to unionfs environment when exiting without full cleanup, .br f.i. 136 = 132 + 4 (remove 100 first; then do binary decoding by 1,..,32; currently only possible combination: 136 since 100 does not combine, only 132 does, no umounting on 132) .SH FURTHER INFORMATION look for detailed usage informations at http://www.elstel.org/xchroot .br get informed about the latest updates via http://www.elstel.org/elstel.rss .br note: your packager may have included an offline version of the respective web page with usage information for xchroot at elstel.org in /usr/share/doc[/packages]/xchroot/index.html .SH SEE ALSO .BR chroot (1), .BR sudo (8), .BR su (1), .BR xauth (1), .BR unionfs-fuse (8), .BR aufs (5), .BR socat (1) .BR unsquashfs (1) .SH AUTHORS .B xchroot was invented, designed and programmed by Elmar Stellnberger <estellnb@elstel.org> (other emails: estellnb@gmail.com, estellnb@yahoo.de). .SH LICENSE This program may be used under the terms of GPLv3; see: https://www.gnu.org/licenses/gpl-3.0.en.html. .br If you apply changes please sign our contributor license agreement at https://www.elstel.org/license/CLA-elstel.pdf so that your changes can be included into the main trunk at www.elstel.org/xchroot/ .br (c) copyright by Elmar Stellnberger 2021
Locations
Projects
Search
Status Monitor
Help
OpenBuildService.org
Documentation
API Documentation
Code of Conduct
Contact
Support
@OBShq
Terms
openSUSE Build Service is sponsored by
The Open Build Service is an
openSUSE project
.
Sign Up
Log In
Places
Places
All Projects
Status Monitor
