Difference between pages "Help:Funtoo Editing Guidelines" and "Install/BootLoader"

From Funtoo
(Difference between pages)
Jump to navigation Jump to search
 
 
Line 1: Line 1:
This guide is meant to serve as a reference for those who are interested in helping improve the Funtoo Wiki.
<noinclude>
{{InstallPart|boot loader configuration}}
</noinclude>
=== Installing a Bootloader ===


First, to perform edits on the wiki, you must {{CreateAccount}} and log in.
These install instructions show you how to use GRUB to boot using BIOS (old-school) or UEFI (new-school).


You can create a new page by navigating to http://www.funtoo.org/New_Page_Name. Underscores are the equivalent of spaces. Then click the "Create" button in the upper right.
==== Old School (BIOS) ====


Whether creating a new page or editing an existing page by clicking "Edit", you will be presented with Web-based text editor that allows you to modify the ''wikitext'' of the page. The wikitext is rendered to produce the document you see when you view the page normally.
If you're using the BIOS to boot, setting up GRUB, the bootloader, is pretty easy.


This wiki uses the ApprovedRevs Extension, which means that any changes you make to a page will need to be approved by an Editor before they are displayed. Editors can visit the [[Special:ApprovedRevs]] page to approve edits made on pages (click "Pages whose approved revision is not their latest" or "Unapproved pages".)
To use this recommended boot method, first emerge <code>boot-update</code>. This will also cause <code>grub-2</code> to be merged, since it is a dependency of <code>boot-update</code>.


Until your edits are approved, you can continue to edit the page and your changes will be displayed in the page's History -- click "View History" in the upper right to view the page's history. You will see that the approved version of a page has a star next to it.
<console>
(chroot) # ##i##emerge boot-update
</console>


Another fun thing you can do is click on your name in the upper right once you have logged in. This will bring you to your "User" page. Then click "Create with Form" and enter your geographic and other information. This will allow you to be displayed on our [[Usermap]] and will also allow your full name to be displayed on [[:Category:Ebuilds|Ebuild pages]] for which you are an author. It's generally a good idea to do this.
Then, edit <code>/etc/boot.conf</code> and specify "<code>Funtoo Linux genkernel</code>" as the <code>default</code> setting at the top of the file, replacing <code>"Funtoo Linux"</code>.  


{{fancytip|The following sections document how to use wikitext and Funtoo templates on the Funtoo wiki.}}
<code>/etc/boot.conf</code> should now look like this:


= Paragraphs =
<pre>
boot {
generate grub
default "Funtoo Linux genkernel"
timeout 3
}


To create a new paragraph, insert a blank line between two lines of text. If a blank line doesn't exist between two lines of wikitext, they will be combined into a single flowing paragraph.
"Funtoo Linux" {
kernel bzImage[-v]
}


If you leave leading whitespace at the beginning of a line, MediaWiki will render it as pre-formatted text. Beware of this. Here's an example:
"Funtoo Linux genkernel" {
 
kernel kernel[-v]
foobar
initrd initramfs[-v]
 
params += real_root=auto
= Page and Section Capitalization =
}
 
In general, capitalize all words in page names and section heading except:
* Articles: a, an, the
* Coordinating Conjunctions: and, but, or, for, nor, etc.
* Prepositions (fewer than five letters): on, at, to, from, by, etc.
 
= Document Heirarchy =
 
Use section headings to create a document heirarchy for your page. These will define the table of contents that appears at the top of the wiki page. Create chapters, sections and sub-sections as follows:
 
<pre>= Page Title =
 
== Chapter Title ==
 
=== Section Title ===
 
==== SubSection Title ====


"Funtoo Linux better-initramfs" {
kernel vmlinuz[-v]
initrd /initramfs.cpio.gz
}
</pre>
</pre>


== Links ==
Please read <code>man boot.conf</code> for further details.


Internal links to other wiki pages can be specified as <tt><nowiki>[[pagename]]</nowiki></tt>. To specify an alternate name for the link, use <tt><nowiki>[[pagename|my link name]]</nowiki></tt>.
===== Running grub-install and boot-update =====


For external links, use <tt><nowiki>[http://funtoo.org my link]</nowiki></tt> to specify a URL. If you want the URL to appear in the wikitext, you can specify it without brackets: http://forums.funtoo.org.
Finally, we will need to actually install the GRUB boot loader to your disk, and also run <code>boot-update</code> which will generate your boot loader configuration file:


== Lists ==
<console>
(chroot) # ##i##grub-install --no-floppy /dev/sda
(chroot) # ##i##boot-update
</console>


MediaWiki supports a number of list formats:
Now you need to update your boot loader configuration file:
 
<console>
* Unordered List
(chroot) # ##i##boot-update
* Unordered Item 2
</console>
** Unordered sub-item
You only need to run <code>grub-install</code> when you first install Funtoo Linux, but you need to re-run <code>boot-update</code> every time you modify your <code>/etc/boot.conf</code> file, so your changes are applied on next boot.
 
# Ordered List
# Ordered Item 2
## Ordered sub-item


;Term: This is called a "definition list". It is used when defining various terms.
==== New School (UEFI) ====


If you need to quote a portion of text from another site, use <tt><nowiki><blockquote></nowiki></tt> as follows:
If you're using UEFI to boot, setting up the boot loader is a bit more complicated for now, but this process will be improving soon. Perform the following steps.


<blockquote>
===== Emerging GRUB =====
Wikipedia (ˌwɪkɨˈpiːdiə/ or wɪkiˈpiːdiə/ wik-i-pee-dee-ə) is a collaboratively edited, multilingual, free-access, free content Internet encyclopedia that is supported and hosted by the non-profit Wikimedia Foundation. Volunteers worldwide collaboratively write Wikipedia's 30 million articles in 287 languages, including over 4.5 million in the English Wikipedia. Anyone who can access the site can edit almost any of its articles, which on the Internet comprise[4] the largest and most popular general reference work.[5][6][7][8][9] In February 2014, The New York Times reported that Wikipedia is ranked fifth globally among all websites stating, "With 18 billion page views and nearly 500 million unique visitors a month..., Wikipedia trails just Yahoo, Facebook, Microsoft and Google, the largest with 1.2 billion unique visitors."[10]
</blockquote>


== Literal Text and HTML Symbols ==
You will still use GRUB as a boot loader, but before emerging grub, you will need to enable EFI booting. To do this,
add the following line to <code>/etc/make.conf</code>:


Here is wikitext for the section above, which I am displaying by placing the literal wikitext between a &#60;pre&#62; and &#60;/pre&#62; tag. If you want to disable wikitext processing for a span of text, use &#60;nowiki&#62; and &#60;/nowiki&#62;. If you want to print out a tag literally, use &amp;#60; and &amp;#62; (In the wikitext, I used &amp;amp;#60; and &amp;amp;#62 to display these!)
For x86-64bit systems:


<pre>
<pre>
* Unordered List
GRUB_PLATFORMS="efi-64"
* Unordered Item 2
** Unordered sub-item
 
# Ordered List
# Ordered Item 2
## Ordered sub-item
 
;Term: This is called a "definition list". It is used when defining various terms.
 
If you need to quote a portion of text from another site, use <tt><nowiki><blockquote></nowiki></tt> as follows:
 
<blockquote>
Wikipedia (ˌwɪkɨˈpiːdiə/ or wɪkiˈpiːdiə/ wik-i-pee-dee-ə) is a collaboratively edited, multilingual, free-access,
free content Internet encyclopedia that is supported and hosted by the non-profit Wikimedia Foundation. Volunteers
worldwide collaboratively write Wikipedia's 30 million articles in 287 languages, including over 4.5 million in the
English Wikipedia. Anyone who can access the site can edit almost any of its articles, which on the Internet
comprise[4] the largest and most popular general reference work.[5][6][7][8][9] In February 2014, The New York
Times reported that Wikipedia is ranked fifth globally among all websites stating, "With 18 billion page views
and nearly 500 million unique visitors a month..., Wikipedia trails just Yahoo, Facebook, Microsoft and Google,
the largest with 1.2 billion unique visitors."[10]
</blockquote>
</pre>
</pre>


== Displaying Source Code ==
For x86-32bit systems:
 
To display source code, use the <tt>&#60;syntaxhighlight&#62;</tt> tag, which has the ability to perform syntax highlighting on the source code for easier reading:
<pre>
<syntaxhighlight lang="python">
import system
</syntaxhighlight>
</pre>
 
This will produce the following output:
 
<syntaxhighlight lang="python">
import system
</syntaxhighlight>
 
Alternatively, if you need a caption, use can use the file template, specifying a <tt>lang=</tt> parameter:
 
<pre>
{{file|name=foobar|lang=python|desc=foobarosity|body=
import system
}}
</pre>
 
This will produce:
 
{{file|name=foobar|lang=python|desc=foobarosity|body=
import system
}}
 
Note that the language should be specified in the <tt>lang</tt> attribute. For a list of supported languages, see [http://www.mediawiki.org/wiki/Extension:SyntaxHighlight_GeSHi#Supported_languages this list].
 
== Displaying Text File Contents ==
 
For displaying the contents of non-programming language text files (like config files), you have two options. You can enclose your lines within <tt>&#60;pre&#62;</tt> tags, or use the new [[Template:File|file template]]. The file template is used like so:


<pre>
<pre>
{{file|name=/etc/foo.conf|desc=My foo.conf file|body=
GRUB_PLATFORMS="efi-32"
# /etc/host.conf:
# $Header: /var/cvsroot/gentoo/src/patchsets/glibc/extra/etc/host.conf,v 1.1 2006/09/29
}}
</pre>
</pre>


This will produce:
Then, <code>emerge boot-update</code>. You will notice <code>grub</code> and <code>efibootmgr</code> getting pulled in as dependencies. This is expected and good:


{{file|name=/etc/foo.conf|desc=My foo.conf file|body=
# /etc/host.conf:
# $Header: /var/cvsroot/gentoo/src/patchsets/glibc/extra/etc/host.conf,v 1.1 2006/09/29
}}
== Console ==
To display console output, use the <tt>&#60;console&#62;</tt> tag:
For a root console:
<pre>
<console>
<console>
###i## run a command as root
(chroot) # ##i##emerge boot-update
</console>
</pre>
Produces:
<console>
###i## run a command as root
</console>
</console>


{{Fancyimportant|The <tt>##i##</tt> text tags the rest of the line as being ''user input'' ("i" is for "input"). It is then highlighted in a noticeable color so it stands out from text that is not typed in by the user.}}
===== Installing GRUB =====
 
Now, for the magic of getting everything in place for booting. You should copy your kernel and initramfs (if you have one -- you will if you are following the default install) to <tt>/boot</tt>. GRUB will boot those. But how do we get UEFI to boot GRUB? Well, we need to run the following command (for 32 bit simply set it as i386-efi):


Examples of usage:
* [[Rootfs over encrypted lvm]]
* [[Boot-Update]]
* [[Fonts]]
For a non-root console:
<pre>
<console>
$ ##i##run a command as user
</console>
</pre>
Produces:
<console>
<console>
$ ##i##run a command as user
(chroot) # ##i##grub-install --target=x86_64-efi --efi-directory=/boot --bootloader-id="Funtoo Linux [GRUB]" --recheck /dev/sda
</console>
</console>
This command will simply install all the stuff to <tt>/boot/EFI</tt> and <tt>/boot/grub</tt> that your system needs to boot. In particular, the <tt>/boot/EFI/grub/grubx64.efi</tt> file will be created. This is the GRUB boot image that UEFI will load and start.


{{fancyimportant|1=
A more detailed explanation of the flags used in the above command:
Note that we use a <tt>#</tt> prompt for <tt>root</tt> and a <tt>$</tt> prompt to denote a non-root user.}}
* <code>--target=x86_64-efi</code>: Tells GRUB that we want to install it in a way that allows it to boot in UEFI
 
* <code>--efi-directory=/boot</code>: All GRUB UEFI files will be installed in ''/boot''
Examples of usage:
* <code>--bootloader-id="Funtoo Linux [GRUB]"</code>: This flag is not necessary for GRUB to boot. However, it allows you to change the text of the boot option in the UEFI BIOS. The stuff in the quotes can be set to anything that you would like.
* [[Zope HOWTO]]
* <code>--recheck</code>: If a device map already exists on the disk or partition that GRUB is being installed on, it will be removed.
* [[Benchmarking]]
* <code>/dev/sda</code>:The device that we are installing GRUB on.


== Fancy Notes ==
===== Configuring GRUB =====
notes, warnings, tips, and important templates will help bring emphasis to articles drawn up.
<pre>{{fancynote|this is a fancy note}}</pre><br />
{{fancynote|this is a fancy note}}<br />


<pre>{{fancyimportant|this is a fancy important}}</pre><br />
OK, now UEFI has the GRUB image it needs to boot. But we still need to configure GRUB itself so it finds and boots your kernel and initramfs. This is done by performing the following steps. Since boot-update doesn't yet support UEFI, we will use boot-update, but then edit our <code>/boot/grub/grub.cfg</code> to support UEFI booting.
{{fancyimportant|this is a fancy important}}<br />


<pre>{{fancywarning|this is a fancy warning}}</pre><br />
First, you will need to edit <code>/etc/boot.conf</code>. Format this as you would if you were booting without UEFI. If you are not sure how this should look, below is an example of what it could look like if you are booting from an unencrypted ext4 partition:
{{fancywarning|this is a fancy warning}}<br />


<pre>{{fancytip|this is a fancy tip}}</pre><br />
{{file|name=/etc/boot.conf|desc=|body=
{{fancytip|this is a fancy tip}}<br />
boot {
        generate grub
        default "Funtoo Linux"
        timeout 3
}


== Kernelop ==
"Funtoo Linux" {
To display kernel configuration options, we encourage you to use the <tt>kernelop</tt> template. To use the <tt>kernelop</tt> template, create an entry similar to the following example:
        kernel vmlinuz[-v]
<pre>
        params += rootfstype=ext4 root=/dev/sda2
{{kernelop|title=foo,bar|desc=
}
kernel options pasted from "make menuconfig"
}}
</pre>
 
{{fancynote|Kernelop is colored blue to slightly resemble the blueish background from <tt>make menuconfig</tt>.}}
 
Adding this entry will give you the following output:
{{kernelop|title=foo,bar|desc=
kernel options
}}
}}


Here's a more concrete example:
After you have edited your <code>/etc/boot.conf</code> file, run <code>boot-update</code>. You should now have a <code>/boot/grub/grub.cfg</code> file, which you can edit using the following command:
{{kernelop|title=File systems|desc=
<M> Second extended fs support         
[ ]  Ext2 extended attributes         
[ ]  Ext2 execute in place support   
<M> Ext3 journalling file system support
}}


Examples of usage:
<console>
* [[Package:AMD Catalyst Video Drivers]]
# ##i##nano /boot/grub/grub.cfg
* [[Package:ACPI Daemon]]
</console>
* [[Microcode]]




== Marking Pages as Needing Updates ==
To get your <code>/boot/grub/grub.cfg</code> to support booting with UEFI, make the following changes. Below the existing insmod lines, add the following lines.  Both of these involve adding support for the UEFI framebuffer to GRUB.:
 
If you find outdated wiki content, but you don't have the time or ability to update it, add one of the following templates to the wikitext of the page. This will add the page to the [[:Category:Needs Updates|Needs Updates Category]] so we can identify pages that need updating:


<pre>
<pre>
{{PageNeedsUpdates}}
  insmod efi_gop
{{SectionNeedsUpdates}}
  insmod efi_uga
</pre>
</pre>


Then, change the <code>set gfxpayload</code> line to read as follows. UEFI does not support text mode, so we will keep video initialized to the current resolution.:


Examples of usage:
* [[UEFI Install Guide]]
* [[Package:MediaWiki]]
* [[Clang]]
== &#60;tt&#62; and &#60;code&#62; ==
To emphasize filenames, commands, and other technical jargon when they appear inline in a paragraph, use the  <tt>&#60;tt&#62;</tt> or <tt>&#60;code&#62;</tt> option. To use these, follow the example below:
<pre>
<pre>
The <tt>/etc/fstab</tt> file is an important one. Another important file is <code>/boot/grub/grub.cfg</code>.
  set gfxpayload=keep
</pre>
</pre>


This example produces the following output (notice the difference between the fonts?): <br> The <tt>/etc/fstab</tt> file is an important one. Another important file is <code>/boot/grub/grub.cfg</code>.
You can now save your changes by pressing <code>Control-X</code> and answering <code>y</code> when asked if you want to save the modified buffer. When prompted for a filename, hit Enter to use the existing filename.
 
== Collapsible text ==
 
<pre><div class="toccolours mw-collapsible"> some text you might want to fold away because its a huge explanation.</div></pre><br />
 
<div class="toccolours mw-collapsible"> some text you might want to fold away because its a huge explanation.</div><br />
 
<pre><div class="toccolours mw-collapsible mw-collapsed">pre collapsed text because it is a huge explanation.</div></pre><br />
 
<div class="toccolours mw-collapsible mw-collapsed">pre collapsed text because it is a huge explanation.</div>
 
== Screencasting ==
screencasting is an easy method to explain complex tasks.  take for instance youtu.be/5KDei5mBfSg we chop off the id and insert it into the following syntax to produce a video example.<br />
tiny:
<pre>{{#widget:YouTube|id=5KDei5mBfSg|width=320|height=180}}</pre>
standard:
<pre>{{#widget:YouTube|id=5KDei5mBfSg|width=700|height=420}}</pre>
{{#widget:YouTube|id=5KDei5mBfSg|width=700|height=420}}
 
[[Category:Wiki Development]]

Revision as of 19:48, January 1, 2015


   Note

This is a template that is used as part of the Installation instructions which covers: boot loader configuration. Templates are being used to allow multiple variant install guides that use most of the same re-usable parts.


Installing a Bootloader

These install instructions show you how to use GRUB to boot using BIOS (old-school) or UEFI (new-school).

Old School (BIOS)

If you're using the BIOS to boot, setting up GRUB, the bootloader, is pretty easy.

To use this recommended boot method, first emerge boot-update. This will also cause grub-2 to be merged, since it is a dependency of boot-update. 

(chroot) # emerge boot-update

Then, edit /etc/boot.conf and specify "Funtoo Linux genkernel" as the default setting at the top of the file, replacing "Funtoo Linux".

/etc/boot.conf should now look like this: 

boot {
	generate grub
	default "Funtoo Linux genkernel" 
	timeout 3 
}

"Funtoo Linux" {
	kernel bzImage[-v]
}

"Funtoo Linux genkernel" {
	kernel kernel[-v]
	initrd initramfs[-v]
	params += real_root=auto 
} 

"Funtoo Linux better-initramfs" {
	kernel vmlinuz[-v]
	initrd /initramfs.cpio.gz
}

Please read man boot.conf for further details.

Running grub-install and boot-update

Finally, we will need to actually install the GRUB boot loader to your disk, and also run boot-update which will generate your boot loader configuration file: 

(chroot) # grub-install --no-floppy /dev/sda
(chroot) # boot-update

Now you need to update your boot loader configuration file: 

(chroot) # boot-update

You only need to run grub-install when you first install Funtoo Linux, but you need to re-run boot-update every time you modify your /etc/boot.conf file, so your changes are applied on next boot.

New School (UEFI)

If you're using UEFI to boot, setting up the boot loader is a bit more complicated for now, but this process will be improving soon. Perform the following steps.

Emerging GRUB

You will still use GRUB as a boot loader, but before emerging grub, you will need to enable EFI booting. To do this, add the following line to /etc/make.conf:

For x86-64bit systems: 

GRUB_PLATFORMS="efi-64"

For x86-32bit systems: 

GRUB_PLATFORMS="efi-32"

Then, emerge boot-update. You will notice grub and efibootmgr getting pulled in as dependencies. This is expected and good: 

(chroot) # emerge boot-update
Installing GRUB

Now, for the magic of getting everything in place for booting. You should copy your kernel and initramfs (if you have one -- you will if you are following the default install) to /boot. GRUB will boot those. But how do we get UEFI to boot GRUB? Well, we need to run the following command (for 32 bit simply set it as i386-efi): 

(chroot) # grub-install --target=x86_64-efi --efi-directory=/boot --bootloader-id="Funtoo Linux [GRUB]" --recheck /dev/sda

This command will simply install all the stuff to /boot/EFI and /boot/grub that your system needs to boot. In particular, the /boot/EFI/grub/grubx64.efi file will be created. This is the GRUB boot image that UEFI will load and start.

A more detailed explanation of the flags used in the above command:

  • --target=x86_64-efi: Tells GRUB that we want to install it in a way that allows it to boot in UEFI
  • --efi-directory=/boot: All GRUB UEFI files will be installed in /boot
  • --bootloader-id="Funtoo Linux [GRUB]": This flag is not necessary for GRUB to boot. However, it allows you to change the text of the boot option in the UEFI BIOS. The stuff in the quotes can be set to anything that you would like.
  • --recheck: If a device map already exists on the disk or partition that GRUB is being installed on, it will be removed.
  • /dev/sda:The device that we are installing GRUB on.
Configuring GRUB

OK, now UEFI has the GRUB image it needs to boot. But we still need to configure GRUB itself so it finds and boots your kernel and initramfs. This is done by performing the following steps. Since boot-update doesn't yet support UEFI, we will use boot-update, but then edit our /boot/grub/grub.cfg to support UEFI booting.

First, you will need to edit /etc/boot.conf. Format this as you would if you were booting without UEFI. If you are not sure how this should look, below is an example of what it could look like if you are booting from an unencrypted ext4 partition:

   /etc/boot.conf 
boot {
        generate grub
        default "Funtoo Linux"
        timeout 3
}

"Funtoo Linux" {
        kernel vmlinuz[-v]
        params += rootfstype=ext4 root=/dev/sda2
}

After you have edited your /etc/boot.conf file, run boot-update. You should now have a /boot/grub/grub.cfg file, which you can edit using the following command: 

root # nano /boot/grub/grub.cfg


To get your /boot/grub/grub.cfg to support booting with UEFI, make the following changes. Below the existing insmod lines, add the following lines. Both of these involve adding support for the UEFI framebuffer to GRUB.: 

  insmod efi_gop
  insmod efi_uga

Then, change the set gfxpayload line to read as follows. UEFI does not support text mode, so we will keep video initialized to the current resolution.: 

  set gfxpayload=keep

You can now save your changes by pressing Control-X and answering y when asked if you want to save the modified buffer. When prompted for a filename, hit Enter to use the existing filename.

Retrieved from "https://www.funtoo.org/index.php?title=Help:Funtoo_Editing_Guidelines&oldid=8101"