Revision as of 21:35, 18 November 2012

There is no requirement to use the sudo command in Sabayon Linux. Use the su command to log-in to the root user's account, perform the steps listed, then type exit to log-out from the root user's account when you have finished. Where stated in this article, you must use this method. A hash (#) prompt indicates you are logged-in as the root user; a dollar ($) prompt indicates you are logged-in under your own account.

About Entropy

The Entropy Project Logo

Entropy is the name of the Sabayon Linux binary package management system. This is the name for the complete infrastructure, composed by Equo client (textual), Sulfur and Rigo client (graphical), Reagent and Activator server applications.

Sabayon is based on Gentoo's testing branch, which is about on par with Debian Sid releases. Entropy takes packages from Gentoo testing and they are pre-compiled, then offered to you in binary form. There is a time delay from when Sabayon compiles these packages for Entropy and when you receive them. It is recommended to only use 1 of the package managers(either Entropy or Portage) to avoid any possible conflicts as a result of the time delay. Generally, Entropy packages will be slightly more stable because they will have already been released in Gentoo testing for a period of time(exact amount of time varies), prior to being released in Entropy.

Installing Entropy

There are 2 supported ways to install Entropy: either using the Sabayon Linux Portage overlay, or by using Equo itself. This is possible as all versions of Sabayon Linux after 3.5 come with Entropy installed by default. It is recommended to use Entropy with all current Sabayon releases.

Note: Installing Entropy in Gentoo Linux or in any other release is not supported officially although it is possible.

Upgrading Entropy using Equo

As of version 3.5 of Sabayon, Entropy has been included by default. To upgrade it to the latest (and greatest) version, open a terminal (such as Konsole in KDE or Terminal in GNOME) and enter the commands shown below.

1. Become root (enter the root password when prompted):

$ su

2. Update the Equo Database:

# equo update

That will update the database to the latest version.

3. Download and install the latest version of Entropy:

# equo install entropy rigo

4. To test it's working, run:

# equo --version

If you get a version number such as:

entropy: 145
equo: 145

Then it has installed and is working!

Installing Entropy using Portage

emerge and layman are Portage commands, Portage is not our package manager but is available to advanced users. Any steps using these commands can be safely ignored

Installing via Portage can be completed using the procedure listed below. Open a terminal (such as konsole) and enter the commands:

1. Become root (enter the root password when prompted):

$ su

2. Update the Sabayon overlays to the latest versions:

# layman --sync sabayon
# layman --sync sabayon-distro

If you get an error message that the overlays do not exist then you need to add them:

# layman --add sabayon
# layman --add sabayon-distro

3. Emerge Entropy, Equo and Rigo to install the latest versions:

# emerge entropy equo rigo

4. To test it's working, run:

# equo --version

If you get a version number such as:

entropy: 136
equo: 136

Then it has installed and is working!

Packages Entropy Downloads

Packages are downloaded and stored in /var/lib/entropy/client/packages/ For instance on amd64 using Branch 5 they are stored in /var/lib/entropy/client/packages/packages/amd64/5

You can use the command below to clean them up:

# equo cleanup

About Equo, the Commandline package Manager

Equo is the command line client-side application for the Entropy package management system. It is capable of installing, removing and updating packages, resolving dependences, reverse dependency handling and configuration file handling and that's just to start with.

Basic Usage

There are several options you can use when using Equo, a few of the basic commands are shown below.

Searching for a package can be accomplished by running the equo search command:

# equo search <package name>

To install a package use the install function, the --ask amendment is optional but recommended.

Sulfur is (yet) still available in the Repositories, but is no longer developed and will most likely NOT work anymore !!!

Sulfur was the (old) GUI (Graphical User Interface) to Equo, the Sabayon Linux Binary Package Manager.
Sulfur will no longer exist in the future so Rigo will be the new and improved GUI package manager for entropy store.

Usage

For a detailed usage guide, please visit the Rigo page which contains a visual walk-through of all the features.

Package Repositories

What are Package Repositories

Repositories are a storage location from which software packages may be retrieved and installed on a computer. Sabayon's Repositories contain over 9000 different packages per architecture (x86/x86_64).

Why are there all these repositories?

Sabayon offers 4 official repositories but by default you only use one of them.

sabayon-hell

Not a place you want to be really. This repository is used by our build system "Matter". The Entropy repository team carefully made lists of packages that could always be updated once a new version gets released in Portage. The build system does nothing more then work down this list and add the packages here. Since they are NOT checked by humans we can never know if the work that was done by the build system is actually what we wanted it to be.
Each monday the Entropy team evaluates what Matter did and moves these packages to sabayon-limbo (testing) repository.

sabayon-limbo

This is the testing repository. All packages that are compiled and packaged are pushed in this repository. Work on this repository goes on 24/7.
While all packages that land here are tested at compilation phase, it is possible they have problems while running them. If you enable this repository keep in mind that things can break, you receive more updates because packages get recompiled and repackaged if needed.

Please note that the sabayon-limbo is an overlay repo, you MUST keep sabayonlinux.org repo enabled!
Otherwise you will have missing dependencies.

sabayonlinux.org

This is the repository mostly refered to as "main". Every monday most, if not all, packages from sabayon-limbo (testing) get moved into this one.

sabayon-weekly

This is by default the only enabled repository. It is a copy of sabayonlinux.org (main) repository. Every saturday night it gets renewed.
This repository was introduced to build in a delay between when packages get moved from testing and are available for all users. This gives packagers additional time to test packages in the main repository and fix issues if any before the copy is made.

How can I enable a different repository?

In /etc/entropy/repositories.conf you find the general configuration that count for all repositories. The different repositories are inherited from a subdirectory: /etc/entropy/repositories.conf.d

In this subdirectory you'll find some predefined examples for the different repositories.

Example how to enable sabayonlinux.org:

# cd /etc/entropy/repositories.conf.d

# mv entropy_sabayonlinux.org.example entropy_sabayonlinux.org

equo update

If you later wish to disable this repository:

# equo disable sabayonlinux.org

Do not combine sabayon-weekly with sabayon-limbo

If you only have sabayon-limbo and sabayon-weekly enabled you will at some point get into a situation where a previously updated package taken from sabayon-limbo wants to downgrade to the version from weekly again. Why does this happen?

As described above packages move from sabayon-limbo into sabayonlinux.org. If you do not have that repository enabled the package manager will fallback on the version it can find, the one in sabayon-weekly. This will cause unwanted downgrades and maybe breakages at some point.

Updating Package Repositories

To update the database of all packages in the repositories in your /etc/entropy/repositories.conf, run (as root):

# equo update

Use the same file to add additional repositories. Currently what is in the repositories.conf file is all that is available.

Note that you can use the following command to optimise the order of the mirrors in /etc/entropy/repositories.conf. This command pings the mirrors and, based on the response times, orders the mirrors in /etc/entropy/repositories.conf accordingly:

# equo repo mirrorsort sabayonlinux.org

Note, however, that

# equo repo mirrorsort sabayon-weekly

seems to be what works in Sabayon 6.0.

Testing repositories:These can break your system, only add them when you really know what you are doing.

Community Repositories

Community Repositories are user-managed packages repositories. Users can recompile packages with different settings, add their own ones and make all available to other people. Repository publishers are responsible for how a package is compiled and what is compiled.

Masking and Unmasking Packages in Entropy

You can find the files to edit in /etc/entropy/packages/ Use package.mask to mask a file, see package.mask.example for more information. Use package.unmask to unmask a file. See package.unmask.example for more information.

Adding Additional Packages Manually

Fresh Install - What to do?

So you just installed a fresh copy of Sabayon Linux and are wondering what to do next.

The first thing to do is of course learn how to use the Entropy package manager. It is vital to know your package manager. So read first, then do.

Using Entropy to upgrade all installed packages

Now that you have learned about the Entropy package manager, let's get our package list for the package manager current. You will have to be root to use the commands, so open a terminal and enter su with the root password and, if you did it correctly, your prompt will change to a hash symbol (#) to show you are now logged in as the root user. DO NOT use sudo.

# equo update

If you run into problems with that then try:

# equo update --force

Next, as mentioned in the section above, it is a good idea to optimize the sorting of mirrors so that all package upgrades will be downloaded as quickly as possible:

# equo repo mirrorsort sabayon-weekly

Once you have that completed it is vital to get Entropy upgraded to the latest version before doing a full system upgrade. Upgrade will bring your system to current development.

# equo install entropy rigo equo --relaxed
# equo conf update

Once the Entropy code is upgraded to the latest version, fully upgrade the rest of your system with these two commands:

# equo update
# equo upgrade --ask

Follow what is happening on the screen, as Entropy will show you what it is going to do and ask for confirmations. The 'equo update' command will update the database on your PC with the latest information on packages available in the Entropy repositories; the 'equo upgrade' command will download from the repositories the binary files for new versions of packages installed on your PC and then install the new versions of those packages. Time of process depends on how many packages, bandwidth and hardware. After it is done, make sure to:

# equo conf update

You will want to make your selection but you really should get to know your config files as they will change your system. More than likely most will select -5. I always look over the config files as I don't want some of my configs getting overwritten.

The final step is to run the following commands, checking for missing dependencies and stability:

# equo deptest
# equo libtest

After this has finished, reboot and enjoy your freshly installed fully updated Sabayon.

The equo upgrade command does not upgrade the kernel if a new version happens to be available in the Entropy repository. If you want to install a newer version of the kernel then you must: a) install the newer kernel manually using equo; b) ensure that the symbolic link to the kernel sources is pointing to the correct version of the kernel sources (by using the 'eselect kernel' command); c) install the corresponding kernel modules manually using equo; d) ensure that the correct OpenGL implementation for your video driver is selected (by using the 'eselect opengl' command); e) ensure the new kernel is included in the menu in grub.conf (SL 5.1-r1 and earlier) or grub.cfg (SL 5.2 and onwards).

What about using Sulfur? I do not recommend using Sulfur for the initial upgrade. Equo is 100x's more reliable and you won't end up with the issues that Sulfur can cause. So do your initial installation with Equo then look at using Sulfur after that.

Upgrading the Linux kernel

For detailed instructions on updating the kernel using Entropy use the following link:

The kernel image is not upgraded automatically; you have to upgrade it manually. You install a new version of the kernel image as you would any other package, i.e. using either the equo command or Sulfur. For example, if you currently have the 2.6.35 kernel image installed on your PC and version 2.6.36 is available in the Entropy repositories then you can install the new version by entering the command:

# equo install sys-kernel/linux-sabayon-2.6.36

Once you have installed a new version of the kernel image you must install the relevant modules your PC requires, which have been compiled specifically for that version of the kernel image. When you do this, you must specify the full package name, including the kernel version, of the modules.

For example, if you had just installed the 2.6.36 kernel image (the Entropy package sys-kernel/linux-sabayon-2.6.36) then you would have to install the relevant modules for it like so:

# equo install x11-drivers/ati-drivers-10.10#2.6.36-sabayon

If you do not include the "#2.6.36-sabayon" in the package name then, if the ati-drivers-10.10 package for an earlier version of the kernel happens to be in the repositories, it would be installed/re-installed instead of the module you need.

The above example assumes you are using the closed-source FGLRX driver for an AMD GPU, but the same principle applies if you are using an NVIDIA closed-source driver with an NVIDIA GPU, or if you are using any other software that is a kernel module (VirtualBox modules are another example).

You must also use the 'eselect kernel' command to make the symbolic link to the kernel sources point to the new version of the kernel sources, and you must use the 'eselect opengl' command to select the correct OpenGL implementation for your video driver. The Entropy kernel image package will take care of upgrading the Grub2 grub.cfg file to include the new kernel image in the Grub menu.

The instructions above assume you are upgrading to a later version of the kernel, but are equally applicable if you are downgrading to an earlier version of the kernel.

Using Kernel Switcher

kernel-switcher is an easy-to-use tool to simplify upgrading the kernel in Sabayon Linux. Remember, doing regular upgrades will not upgrade the kernel: you need to invoke a kernel change. This is done to prevent users from breaking their system and then screaming in the forums or in irc.

The kernel-switcher list command is a nice feature, but can be overwhelming as it lists all kernels currently available in the repository. You may prefer to use equo search linux-sabayon as linux-sabayon is the Sabayon kernel package. With equo search linux-sabayon you can see if any newer kernels exist. For example, if you find that linux-sabayon-2.6.38 is available as an upgrade, you would upgrade to it as follows:

Notice it pulls the new kernel plus new versions of kernel modules/drivers that are currently installed. Let it download and install everything needed for the new kernel. Once this is done, GRUB 2 will reflect the change so that, when you reboot, the new kernel is available to select. A few other things need to be done before you reboot: Sometimes the OpenGL libraries get reset and the user finds video is not working properly, so you need to check and set them back:

In the above example the asterisk indicates that the nvidia OpenGL libraries are selected, which I do need. If it was set to xorg-x11, I would use the following command to select the closed-source OpenGL libraries:

You should also update the Portage package list in case you need to use Portage to install the latest version of Entropy if you run into trouble upgrading Entropy using the Entropy commands listed earlier. This step is optional but, if you have problems getting Entropy working, you will need to perform this step to get the latest version of Entropy from the Sabayon Portage overlays.

If you get an error message that the Sabayon overlays do not exist then you need to add them:

# layman --add sabayon
# layman --add sabayon-distro

Note: the first emerge --sync is a little time consuming, but it's a one-time deal.

Now, if you have problems getting the equo update to function or problems getting latest Entropy installed, you can use emerge to get the latest version instead. Follow below for how to install Entropy via Portage:

# emerge entropy equo rigo

Hopefully now you are ready to start the upgrading process:

# equo upgrade --ask

Before you reboot you should check some things first: Please look at this thread to see what I mean. There can be critical things to take care of first before you can safely reboot. Generally it's not a big issue, but a kernel change does require some additional work. You will need to reinstall your drivers/modules to match the kernel.

Make sure you also grab the kernel sources:

# equo install sabayon-sources

You should also keep your Portage ebuild list updated from time to time, just to be safe. You don't have to do it daily, but maybe once a week.

Note: you do not have to do this step at all, until or unless you run into problems. The following step only speeds up the process later by wasting the time doing it now:

If you get an error message that the Sabayon overlays do not exist then you need to add them:

# layman --add sabayon
# layman --add sabayon-distro

Hopping Branches

Since branch 5, SabayonLinux became a 'Rolling Release', so 'hopping' is not needed anymore. Just upgrade the system as stated above.
The following is only for people running branch 4.2, 4.1, or 4.

Switching branches is as easy as typing equo hop [branch], replace the [branch] with the one you want to hop to. So let's say we are using Sabayon Linux 4.2 and want to jump to branch 5, all we have to do is:

-- check your kernel with eselect kernel list and make sure it is correct latest kernel selected, it will have the * next to it.
-- check gcc version gcc-config -l and make sure it is on latest one
-- check binutils-config -l and make sure it's set
-- check eselect opengl list for right driver
-- check /boot/grub/grub.conf to make sure it updated properly
-- check eselect python list and make sure it's set to the latest one

Do not ever go backwards with your branches, meaning, don't go from Branch 5 back to Branch 4.

Testing Branch / Rolling Releases

Warning - Read first

This branch of Entropy is dangerous. Read this section from beginning to end before doing anything with it.

Let us quickly go through the most common factors that make running the testing branch impractical:

A good amount of experience with Portage and related tools is crucial to fix problems that are likely to arise when using the testing branch. Reporting problems encountered on this branch is good and helps with the Sabayon development process, but it is not a way for you to get a fix quickly. Only Portage is likely to do that for you.

Solid understanding of Linux (OS including programs) is highly important, too. You can expect to be confronted with new configuration options and non-trivial problems. You will need pretty extensive knowledge to either diagnose and solve, or work around these problems, at a point in time when they have little to no distribution-specific documentation yet - sometimes not even any good documentation at all.

High maintenance - just to explicitly state the other consequence of the two points directly above.

High bandwidth consumption - there are some package upgrades almost every day, and the amount of upgrades can easily hit a few hundred MB every week.

If you have any doubt about meeting one or more of the criteria outlined before, but need or want to use the testing branch / rolling releases anyway, it is strongly recommended that you make use of some virtualization software (and its snapshotting features), rather than deploying the testing branch in your main installation. That way, if some operation goes wrong, you typically won't need to resolve any issues, but can just revert to the last working snapshot - which will in turn allow you to try a more selective operation, or simply defer the operation until later. Modern virtualization software can interact fairly nicely with the host, like displaying windows as if they were part of the host, or share files between host and guest, so this should be the way to go even if you need the most recent version of some program in day-to-day use.

Basically use it on your own risk, don't blame us if anything breaks and your system doesn't work since its unsupported at this stage. We did tell you about the risks and what is good to think over before adding the limbo repo.

Setting it up

Our next release is from packages that are put into the Limbo Repository. This will keep you rolling consistently all the time. This prevents the large amount of packages that hops cause. You will run into bugs/issues at times, but they are usually sorted pretty quickly.

So after adding that line you can then simply do:

# equo update

# equo upgrade

How often you do it is up to you. Once a day or once a week, whatever works for you.

Adding Entropy Mirror

The file to edit: /etc/entropy/repositories.conf

You may notice a big slowdown with Entropy and the Limbo Repo, so please add this mirror under your existing Limbo line: