Difference between pages "Initramfs" and "Repository Configuration"

(Difference between pages)
 
(New repository layout)
 
Line 1: Line 1:
== What is initramfs? ==
+
{{Warning|This article is a work-in-progress referring to a future Portage version. It does not apply to the current Funtoo Portage version. Please do not update your configuration yet.}}
Wikipedia defines initramfs as:
+
<blockquote>
+
initramfs, abbreviated from "initial ram file system", is the successor of initrd. It is a cpio archive of the initial file system that gets loaded into memory during the Linux startup process. The Linux kernel mounts it as root file system and starts the init process from it. This will complete certain tasks before the real root file system is loaded; thus, initramfs needs to contain all of the device drivers and tools needed to mount the real root filesystem.
+
</blockquote>
+
  
== Do I need an initramfs? ==
+
Starting with Portage-2.3.8, a switch to a new repository configuration framework is complete and users may want to update their configuration files. This document aims to describe the goals for the new framework and how to use it.
The reason to build a kernel with an initramfs is mostly for interoperability (e.g. live-cd's) and special features like an included busybox, ssh, etc. But mostly, and that's why we are doing this here now, to have a proper kernel up and running quick'n dirty in a reasonable time without fighting hours and days until a more or less exotic hardware is perfectly run by the kernel. After having a proper basic kernel running with the help of an initramfs, I really recommend you to go a step further and build a true kernel with all features includes without an initramfs. However, relying only on a kernel to boot a system can be quite time consuming, so we have provided several initramfs options for Funtoo. If you have decided to use an initramfs, not just a kernel, check out the options below and choose the one that you like the most.
+
  
== better-initramfs ==
+
== Multiple repository layout ==
Piotr's better-initramfs is a popular approach among Funtoo'ers to building an initramfs. It is quick, nice, and shiny. The biggest plus is that, once built, it is kernel version independent.  
+
One of the most important changes is the switch from the old ''overlay'' layout to a new cleaner ''repository'' system. The new layout is more flexible and more predictable. For example, repositories can now use resources (eclasses, for example) provided by other repositories.
  
=== Installation ===
+
The old layout was based on the concept of one ''main tree'' and optionally a number of overlays. The main tree provided base system ebuilds, eclasses, profiles, while overlays mostly were able to provide their own ebuilds. The ebuild provided by overlays overrode the ebuilds in main tree to the extend of making it impossible to install the main tree version. Overlays could also provide eclasses for their own ebuilds and package.* entries that applied to all overlays and to the main tree. The Package Manager is responsible for updating the main tree, while overlays are managed externally.
To install better-initramfs on your system, change to the <code>/opt</code> directory (or any other directory that you deem suitable) and clone the better-initramfs repository from bitbucket.
+
<console>
+
###i## cd /opt
+
###i## git clone https://bitbucket.org/piotrkarbowski/better-initramfs.git
+
</console>
+
  
=== Building <code>/initramfs.cpio.gz</code> ===
+
The new layout is based on the concept of one or more configurable repositories. Each repository can either be stand-alone or depend upon other repositories. The distribution provides a repository called ''funtoo'' (a drop-in replacement for Gentoo's ''gentoo'' repository). Users can install more repositories at they will, the repositories providing their own ebuilds, eclasses and profiles as necessary and/or using them from other repositories. Users can explicitly choose the repository they want to install packages from. The Package Manager can update all repositories.
Now that you have better-initramfs on your system, we can make the <code>initramfs.cpio.gz</code> image and move it to <code>/boot</code>.
+
{{fancynote| do not run <code>make prepare</code> or <code>make image</code> until you have configured your kernel. If you have not installed / configured a kernel yet, check out: [[Building_a_Kernel_from_Source| Building a Kernel From Source]] and [[Funtoo_Linux_Kernels| Funtoo Linux Kernels]].}}
+
<console>
+
###i## cd better-initramfs
+
###i## bootstrap/bootstrap-all
+
###i## make prepare
+
###i## make image
+
###i## cp output/initramfs.cpio.gz /boot
+
</console>
+
  
=== Configuring <code>/etc/boot.conf</code> ===
+
== Portage configuration ==
Now that the <code>initramfs.cpio.gz</code> file is in <code>/boot</code>, we can configure what we want the initramfs to do for us when the system boots. Below is a table of options that better-initramfs supports (from [https://bitbucket.org/piotrkarbowski/better-initramfs better-initramfs Bitbucket page]):
+
=== New repository layout ===
==== Options ====
+
The repository configuration should be stored in <code>/etc/portage/repos.conf</code>. It can be either a single file or a directory containing one or more ''.conf'' files.
{| {{table}}
+
!Option
+
!Description
+
|-
+
|rescueshell
+
|Drop to the rescueshell before mounting rootfs to <code>/newroot</code>
+
|-
+
|sshd
+
|Run the sshd server when the initramfs loads. This allows you to ssh into your initramfs to fix any errors that may have occurred while booting.
+
|-
+
|sshd_wait=x
+
|Wait x number of seconds after starting sshd to continue booting the system.
+
|-
+
|sshd_port=x
+
|Change the port that sshd "listens" on. The default port for sshd is port 22.
+
|-
+
|binit_net_if=interface
+
|Choose which interface the network should be configured on. For example: wlan0, eth0, etc.
+
|-
+
|binit_net_addr=<ipaddr/cidr>
+
|Configure <code>ipaddr</code> with <code>cidr</code> netmask. For example: <code>11.11.11.2/24</code>. If you do not add a netmask, the netmask is assumed to be 32. Furthermore, you will have to configure <code>binit_net_gw</code>.
+
|-
+
|binit_net_gw=ipaddr
+
|The address of your gateway. Only needed if you want to connect to WAN.
+
|-
+
|rw
+
|Mount the rootfs as read-write. By default, the rootfs is mounted as read only.
+
|-
+
|mdev
+
|Use mdev instead of devtmpfs. This option can prove handy on older kernels.
+
|-
+
|softraid
+
|Detect and run RAID arrays.
+
|-
+
|init=
+
|Change the init system. For example, if you are using systemd, change this to <code>/usr/lib/systemd/systemd</code>. The default for this option (<code>/sbin/init</code>) will work fine with OpenRC.
+
|-
+
|tuxonice
+
|Try resuming with TuxOnIce.
+
|-
+
|uswsusp
+
|Try resuming the system with userspace software suspend. This depends on the <code>resume</code> option.
+
|-
+
|swsusp
+
|Try resuming the system with in-kernel suspend. This depends on the <code>resume</code> option.
+
|-
+
|resume=<device/path>
+
|Specify the device and path from which you want to resume.
+
|-
+
|lvm
+
|Scan for volume groups. If any are found, activate them.
+
|-
+
|luks
+
|Run <code>cryptsetup luksOpen</code> on the <code>enc_root</code> variable.
+
|-
+
|luks_trim
+
|Enable support for TRIM on your LUKS encrypted root device. This option is very helpful for those using SSDs.
+
|-
+
|enc_root=<device>
+
|The device that you wish to decrypt using <code>cryptsetup luksOpen</code>.
+
|-
+
|root=<device>
+
|The name of your root device.
+
|-
+
|rootfstype=<fstype>
+
|Specify the type of filesystem that your rootfs uses.
+
|-
+
|rootdelay=<time (as integer)>
+
|How long the initramfs should wait before attempting to mount devices.
+
|-
+
|rootflags=x
+
|Pass x flags to <code>mount</code> as it mounts your rootfs.
+
|}
+
  
==== Examples ====
+
The default configuration is installed as <code>/usr/share/portage/config/repos.conf</code>. This file is internal configuration file installed with portage ebuild and should '''not''' be modified. Instead, the configuration in <code>/etc/portage/repos.conf</code> can override the defaults specified there.
Below are examples of different use cases for better-initramfs and how your <code>/etc/boot.conf</code> should be configured for them.  
+
{{fancynote| Realize that your <code>enc_root</code>, <code>root</code>, and <code>rootfstype</code> variables may be different from the examples provided below.}}
+
==== Encrypted root with lvm ====
+
{{file|name=/etc/boot.conf|desc= |body=
+
"Funtoo Linux" {
+
kernel vmlinuz[-v]
+
initrd /initramfs.cpio.gz
+
params += enc_root=/dev/sdaX lvm luks luks_trim root=/dev/mapper/funtoo--vg-root rootfstype=ext4
+
}
+
}}
+
  
==== Encrypted root with lvm and RAID ====
+
The configuration uses format similar to Windows .ini files. Each section heading (repository name in square brackets) signifies a single repository, followed by one or more key-value option pairs. For example, the following file copies default configuration for Funtoo repository:
{{file|name=/etc/boot.conf|desc= |body=
+
 
"Funtoo Linux" {
+
{{file|name=/etc/portage/repos.conf/funtoo.conf|desc=Example configuration override for Funtoo repository|body=
kernel vmlinuz[-v]
+
[funtoo]
initrd /initramfs.cpio.gz
+
# moved to non-default location!
params += enc_root=/dev/md0 lvm luks luks_trim softraid root=/dev/mapper/funtoo--vg-root rootfstype=ext4
+
location = /var/db/repos/funtoo
}
+
sync-type = git
 +
sync-uri = git://github.com/funtoo/ports-2015.git
 +
auto-sync = yes
 
}}
 
}}
[[Category:Kernel]]
+
Location variable is now what used to be a PORTDIR, when using old-fashioned <code>/etc/portage/make.conf</code>.  <code>/var/db/repos/funtoo</code> is a dummy location example. Default location in Funtoo is  set to <code>/usr/portage</code>. Users are free to choose a location of their suits. sync-type is a CVS tree used for portage tree, git is a default in Funtoo. sync-uri is what used to be a SYNC variable, when using old-fashioned configuration through <code>/etc/portage/make.conf</code>
 +
The most useful repository configuration options are listed below:
 +
;location: ''Obligatory.'' Specifies the directory where repository is/will be stored. If Portage knows how to sync the repository and the location does not exist, it will be created on next ''emerge --sync''. Otherwise, the directory must exist.
 +
;priority: Specifies the priority used for ordering ebuilds from different repositories. If two repositories provide an ebuild with matching versions, the repository with higher priority will be used.
 +
;auto-sync: Specifies whether ''emerge --sync'' should update the repository. Defaults to ''yes'' if ''sync-type'' is specified, ''no'' otherwise.
 +
;sync-depth: Specifies ''--depth'' for git clone. Used only on initial sync. Defaults to 1. Can be set to 0 to force full clone (not pass ''--depth'' at all).
 +
;sync-type: Specifies syncing/update method. Can be one of: ''cvs'', ''git'', ''rsync'', ''svn''.
 +
;sync-umask: Specifies the umask used when updating/syncing the repository.
 +
;sync-uri: Specifies remote URI from which the repository will be cloned/synced. Can use any syntax valid for a particular syncing method.
 +
;sync-user: Specifies the user[:group] used to update/sync the repository. If ''FEATURES=usersync'' is used, defaults to the credentials of directory owner.
 +
 
 +
[[Category:Portage]]

Revision as of 13:52, February 14, 2015

Warning

This article is a work-in-progress referring to a future Portage version. It does not apply to the current Funtoo Portage version. Please do not update your configuration yet.

Starting with Portage-2.3.8, a switch to a new repository configuration framework is complete and users may want to update their configuration files. This document aims to describe the goals for the new framework and how to use it.

Multiple repository layout

One of the most important changes is the switch from the old overlay layout to a new cleaner repository system. The new layout is more flexible and more predictable. For example, repositories can now use resources (eclasses, for example) provided by other repositories.

The old layout was based on the concept of one main tree and optionally a number of overlays. The main tree provided base system ebuilds, eclasses, profiles, while overlays mostly were able to provide their own ebuilds. The ebuild provided by overlays overrode the ebuilds in main tree to the extend of making it impossible to install the main tree version. Overlays could also provide eclasses for their own ebuilds and package.* entries that applied to all overlays and to the main tree. The Package Manager is responsible for updating the main tree, while overlays are managed externally.

The new layout is based on the concept of one or more configurable repositories. Each repository can either be stand-alone or depend upon other repositories. The distribution provides a repository called funtoo (a drop-in replacement for Gentoo's gentoo repository). Users can install more repositories at they will, the repositories providing their own ebuilds, eclasses and profiles as necessary and/or using them from other repositories. Users can explicitly choose the repository they want to install packages from. The Package Manager can update all repositories.

Portage configuration

New repository layout

The repository configuration should be stored in /etc/portage/repos.conf. It can be either a single file or a directory containing one or more .conf files.

The default configuration is installed as /usr/share/portage/config/repos.conf. This file is internal configuration file installed with portage ebuild and should not be modified. Instead, the configuration in /etc/portage/repos.conf can override the defaults specified there.

The configuration uses format similar to Windows .ini files. Each section heading (repository name in square brackets) signifies a single repository, followed by one or more key-value option pairs. For example, the following file copies default configuration for Funtoo repository:

/etc/portage/repos.conf/funtoo.conf - Example configuration override for Funtoo repository
[funtoo]
# moved to non-default location!
location = /var/db/repos/funtoo
sync-type = git
sync-uri = git://github.com/funtoo/ports-2015.git
auto-sync = yes

Location variable is now what used to be a PORTDIR, when using old-fashioned /etc/portage/make.conf. /var/db/repos/funtoo is a dummy location example. Default location in Funtoo is set to /usr/portage. Users are free to choose a location of their suits. sync-type is a CVS tree used for portage tree, git is a default in Funtoo. sync-uri is what used to be a SYNC variable, when using old-fashioned configuration through /etc/portage/make.conf The most useful repository configuration options are listed below:

location
Obligatory. Specifies the directory where repository is/will be stored. If Portage knows how to sync the repository and the location does not exist, it will be created on next emerge --sync. Otherwise, the directory must exist.
priority
Specifies the priority used for ordering ebuilds from different repositories. If two repositories provide an ebuild with matching versions, the repository with higher priority will be used.
auto-sync
Specifies whether emerge --sync should update the repository. Defaults to yes if sync-type is specified, no otherwise.
sync-depth
Specifies --depth for git clone. Used only on initial sync. Defaults to 1. Can be set to 0 to force full clone (not pass --depth at all).
sync-type
Specifies syncing/update method. Can be one of: cvs, git, rsync, svn.
sync-umask
Specifies the umask used when updating/syncing the repository.
sync-uri
Specifies remote URI from which the repository will be cloned/synced. Can use any syntax valid for a particular syncing method.
sync-user
Specifies the user[:group] used to update/sync the repository. If FEATURES=usersync is used, defaults to the credentials of directory owner.