View source for 32-bit Chroot

<translate>
<!--T:1-->
The 1.3-release of Funtoo Linux deprecates support for 32-bit applications and libraries on x86-64bit arch via 'multilib' -- for more information see [https://forums.funtoo.org/topic/1866-important-13-release-to-beta-and-removal-of-multilib/ this forums post]. This page provides background for this decision as well as steps that can be used to provide 32-bit support without multilib, namely a 32-bit chroot.

== Background == <!--T:2-->

<!--T:3-->
The [https://en.wikipedia.org/wiki/X86 x86 Instruction Set Architecture] includes 64-bit registers which have been implemented in processors from AMD, Intel and others starting in 2003 (AMD Opteron). 

<!--T:4-->
Since then most new and existing applications have been written to make use of x86-64bit architecture. Fewer applications require 32-bit support. In the past, x86-64bit arch on Funtoo Linux has provided support for 64 and 32-bit applications and libraries simultaneously -- called  'multilib' -- which is a capability that is part of the GNU C library and dynamic library loader. 

<!--T:5-->
However, multilib support makes ebuild maintenance more complex, and we have had 64-bit instructions for 15+ years, and fewer and fewer things truly need 32-bit support. Therefore it makes sense to start to transition to a pure 64-bit non-multilib environment to reduce the complexity of ebuilds, and look at other approaches to solve the 32-bit compatibility problem.

== Options == <!--T:6-->

<!--T:7-->
Users needing to run 32-bit programs on x86-64bit hardware have several options:

<!--T:8-->
# install a second separate instance of Funtoo Linux using x86-32bit arch builds.
# install an x86-32bit arch instance of Funtoo Linux on an x86-64bit host. Users then chroot into the 32-bit chroot environment using the {{c|linux32}} (i.e. {{c|setarch}}) command provided by {{package|sys-apps/util-linux}}. This guide will detail the setup and use of this second scenario.
# use [[LXD]] to set up a 32-bit container.

<!--T:9-->
See [[Chroot and Containers]] for a full list of options documented on the wiki.

== Installation == <!--T:10-->
This guide describes a 32-bit chroot installed into a new directory on existing storage.
{{console|body=
$ ##i##su -
Password:
# ##i##mkdir -p /path/to/chroot/directory
# ##i##cd /path/to/chroot/directory
}}

<!--T:11-->
Similar to a Funtoo [[Install/Download_and_Extract_Stage3|installation]] an appropriate Stage3 tarball must be downloaded and extracted. This will provide the directories, files and links necessary for the 32-bit chroot.

<!--T:12-->
'''Please refer to the [[Subarches]] page for an appropriate 32-bit Stage3.''' The following x86-32bit builds would be appropriate on an x86-64bit host

<!--T:13-->
{{TableStart}}
{{2ColHead|Subarch|CPU Family}}
{{2Col|[[Generic 32]]|32-bit Processors (PC-Compatible, Generic)}}
{{2Col|[[I686]]|32-bit Processors (PC-Compatible, Generic)}}
{{2Col|[[Atom 32]]|32-bit Intel Processors}}
{{2Col|[[Pentium4]]|32-bit Intel Processors}}
{{TableEnd}}

<!--T:14-->
You should choose a 32-bit subarch with features and CPU_FLAGS that are compatible with the subarch and CPU of your x86-64bit host. '''If in doubt, choose 'Generic 32'.'''

<!--T:15-->
Copy the download link address for the '''1.3-release-std''' build and paste it into your terminal to download using {{c|wget}}.
{{console|body=
# ##i##wget https://build.funtoo.org/1.3-release-std/x86-32bit/generic_32/2018-12-13/stage3-generic_32-1.3-release-std-2018-12-13.tar.xz
}}

<!--T:16-->
From within your 32-bit chroot directory, run the following command to extract the Stage3 tarball, preserving permissions:
{{console|body=
# ##i##tar -xpf stage3-generic_32-1.3-release-std-2018-12-13.tar.xz
}}

<!--T:17-->
Instead of having duplicate portage trees, this 32-bit chroot will instead use the meta-repo of the 64-bit host. To further eliminate duplicate downloads you can also use the local Portage sourcefile directory on the host inside of the chroot (see 'DISTDIR' in {{c|emerge --info}}). Package source files already fetched by the host will then be available for use by Portage inside of the chroot.

<!--T:18-->
To achieve this you must first create the necessary directories inside of the 32-bit chroot folder. Later the host folders will bind-mount onto these empty directories.
{{console|body=
# ##i##mkdir -p var/git/meta-repo
# ##i##mkdir -p var/cache/portage/distfiles
}}

<!--T:19-->
{{package|sys-apps/portage}} and other packages must only see the environment variables of the 32-bit chroot and not those of the 64-bit host. The Gentoo guide requires users to execute {{c|env-update}} each time you enter the 32-bit chroot environment. The following configuration will set this to occur automatically.

<!--T:20-->
Create and edit the file {{f|.bash_profile}} inside of the directory {{f|/part/to/chroot/directory/root/}} to include the following
{{console|body=
# ##i##nano root/.bash_profile
}}
{{file|name=.bash_profile|desc=/root/.bash_profile inside of /path/to/chroot/directory/|body=
#run env-update on 32-bit chroot login
env-update
}}

<!--T:21-->
As the last step you should configure {{package|app-shells/bash}} to display a modified command prompt while inside of the chroot environment. This will help you to identify when you are issuing commands inside of the 32-bit chroot as opposed to the x86-64bit host.

<!--T:22-->
Add the following line at the end of the file {{f|profile}} inside of the directory {{f|/part/to/chroot/directory/etc/}}
{{console|body=
# ##i##nano etc/profile
}}
{{file|name=profile|desc=/etc/profile inside of /path/to/chroot/directory/|body=

        <!--T:23-->
# understand sequences such as \h, don't put anything special in it.
        PS1="${USER:-$(whoami 2>/dev/null)}@$(uname -n 2>/dev/null) \$ "
fi

<!--T:24-->
# ADD THE FOLLOWING LINE TO IDENTIFY YOUR 32-BIT CHROOT ENVIRONMENT
PS1="(32-bit chroot) ${PS1}"

<!--T:25-->
for sh in /etc/profile.d/*.sh ; do
        [ -r "$sh" ] && . "$sh"
done
unset sh

<!--T:26-->
}}

== OpenRC Configuration == <!--T:27-->
You can create an {{Package|sys-apps/openrc}} service named '''chroot32''' to automatically copy files and mount directories prior to accessing the 32-bit chroot environment. This service will include additional mounts for meta-repo and the Portage DISTDIR.

<!--T:28-->
{{note|The following file mounts Funtoo portage tree /var/git/meta-repo as read-only. The Portage DISTDIR (/var/cache/portage/distfiles) is mounted read-write.}}

<!--T:29-->
Create and edit the file {{f|/etc/init.d/chroot32}}, setting chroot_dir to equal {{f|/path/to/chroot/directory}}.
{{console|body=
# ##i##nano /etc/init.d/chroot32
}}
{{file|name=chroot32|desc=/etc/init.d/chroot32 on x86-64bit host|body=
#!/sbin/openrc-run

<!--T:30-->
chroot_dir=/path/to/chroot/directory

<!--T:31-->
depend() {
   need localmount bootmisc
}

<!--T:32-->
start() {
    ebegin "Mounting 32-bit chroot directories"
    mount --rbind /dev "${chroot_dir}/dev" >/dev/null
    mount --rbind /sys "${chroot_dir}/sys" >/dev/null
    mount -t proc none "${chroot_dir}/proc" >/dev/null
    mount -o bind /tmp "${chroot_dir}/tmp" >/dev/null
    mount -o bind,ro /var/git/meta-repo "${chroot_dir}/var/git/meta-repo/" >/dev/null
    mount -o bind /var/cache/portage/distfiles "${chroot_dir}/var/cache/portage/distfiles/" >/dev/null
    mount -t tmpfs -o nosuid,nodev,noexec,mode=755 none "${chroot_dir}/run" > /dev/null
    eend $? "An error occured while attempting to mount 32bit chroot directories"
    ebegin "Copying 32bit chroot files"
    cp -pf /etc/resolv.conf /etc/passwd /etc/shadow /etc/group \
           /etc/gshadow /etc/hosts "${chroot_dir}/etc" >/dev/null
    cp -Ppf /etc/localtime "${chroot_dir}/etc" >/dev/null
    eend $? "An error occured while attempting to copy 32 bits chroot files."
}

<!--T:33-->
stop() {
    ebegin "Unmounting 32-bit chroot directories"
    umount -fR "${chroot_dir}/dev" >/dev/null
    umount -fR "${chroot_dir}/sys" >/dev/null
    umount -f "${chroot_dir}/proc" >/dev/null
    umount -f "${chroot_dir}/tmp" >/dev/null
    umount -f "${chroot_dir}/var/git/meta-repo/" >/dev/null
    umount -f "${chroot_dir}/var/cache/portage/distfiles/" >/dev/null
    umount -f "${chroot_dir}/run"
    eend $? "An error occured while attempting to unmount 32bit chroot directories"
}

<!--T:34-->
}}

<!--T:35-->
Set this file to be executable.
{{console|body=
# ##i##chmod +x /etc/init.d/chroot32
}}

<!--T:36-->
Start the {{c|chroot32}} service to prepare the 32-bit environment.
{{console|body=
# ##i##rc-service chroot32 start##!i##
 {{!}} ##g##*##!g## Mounting 32-bit chroot directories...                        [ ##g##ok##!g## ]
 {{!}} ##g##*##!g## Copying 32bit chroot files...                                [ ##g##ok##!g## ]
}}

<!--T:37-->
{{tip|If you would like this service to run during host startup issue the following command
{{console|body=
# ##i##rc-update add chroot32 default
 ##g##*##!g## service chroot32 added to runlevel default
}}
}}

<!--T:38-->
The 32-bit chroot environment is now ready for access.

== Enter 32-bit Chroot == <!--T:39-->
Enter the 32-bit chroot environment with the following commands
{{console|body=
$ ##i##su -
Password: ##i##*******
# ##i##linux32 chroot /path/to/chroot/directory /bin/bash -l##!i##
>>> Regenerating /etc/ld.so.cache...
%chroot32%
}}

<!--T:40-->
{{important|The switch '''-l''' tells bash to source /etc/profile within the chroot environment and not from the host. Without this switch you must manually issue the command {{c|source /etc/profile}} each time you enter the 32-bit environment.}}

<!--T:41-->
Confirm that you are now in a 32-bit environment
{{console|body=
%chroot32% ##i##uname -m##!i##
i686
%chroot32% ##i##epro show##!i##

=== ##g##Enabled Profiles:##!g## === <!--T:42-->

        <!--T:43-->
arch: ##bl##x86-32bit##!bl##
       build: ##bl##current##!bl##
     subarch: ##bl##generic_32##!bl##
      flavor: ##bl##core##!bl##
     mix-ins: (not set)


=== ##g##Python kit:##!g## === <!--T:44-->

      <!--T:45-->
branch: ##bl##3.7-release##!bl##

=== ##g##All inherited flavor from core flavor:##!g## === <!--T:46-->

                         <!--T:47-->
##bl##minimal##!bl## (from core flavor)

<!--T:48-->
}}

== Chroot First Steps == <!--T:49-->
If necessary now is a good point to set up [[Funtoo_Linux_Localization|Localization]]. Similarly, changes to {{f|/etc/portage/make.conf}} within the 32-bit environment can be made.

<!--T:50-->
Currently you are the '''root''' user inside of the 32-bit environment. To change to the host user account '''localuser''' you must first create a home directory for localuser inside the 32-bit environment. ({{f|/home/localuser}} '''on the host''' is not mounted inside of this chroot environment.)
{{console|body=
%chroot32% ##i##cp -r /etc/skel /home/localuser##!i##
%chroot32% ##i##chown -R localuser:localuser /home/localuser##!i##
}}

<!--T:51-->
Switch to 'localuser' 
{{console|body=
%chroot32% ##i##su localuser -l
$
}}

== Updating Funtoo Meta-Repo == <!--T:52-->

<!--T:53-->
{{warning|The 32-bit chroot environment uses the Meta-Repo ({{f|/var/git/meta-repo}}) of the 64bit host. Issuing {{c|ego sync}} is not necessary within the 32-bit chroot environment.}}

<!--T:54-->
You must update Meta-Repo on the x86-64bit host ''before'' entering the 32-bit environment.

== Exiting the 32-bit Chroot == <!--T:55-->
{{console|body=
%chroot32% ##i##exit
#
}}

== Emerging Packages == <!--T:56-->
Enter the 32-bit chroot environment and install packages normally.
{{console|body=
$ ##i##su -
Password: ##i##*******
# chroot /path/to/chroot/directory /bin/bash -l
>>> Regenerating /etc/ld.so.cache...
%chroot32% ##i##emerge -av foobar
}}

<!--T:57-->
{{tip|Depending on your use case it may be beneficial to change flavor and add mix-ins within the 32-bit environment.}}

== Wine (32-bit only) == <!--T:58-->
{{important|'''Before''' entering the 32-bit environment run the following command
{{console|body=
$ ##i##su -
Password: ##i##*******
# ##i##xhost local:localhost}}

<!--T:59-->
'''This will allow X11 applications inside of the 32-bit environment to display on the host X session.'''
}}

<!--T:60-->
Install Wine inside of the 32-bit environment (example, {{Package|app-emulation/wine-vanilla}})
{{console|body=
%chroot32% ##i##emerge -av wine-vanilla
}}

<!--T:61-->
Instead of running wine as the '''root''' user, run as '''localuser'''. Switch to 'localuser' and configure Wine with {{c|winecfg}}. An X window should display.
{{console|body=
%chroot32% ##i##su localuser -l
%chroot32% ##i##winecfg
}}

== Acknowledgement == <!--T:62-->

<!--T:63-->
The information published here is based on steps detailed on the Gentoo Linux Wiki: https://wiki.gentoo.org/wiki/Project:AMD64/32-bit_Chroot_Guide ([https://creativecommons.org/licenses/by-sa/3.0/ CC BY-SA 3.0]).
</translate>
[[Category:Official Documentation]]