convert documentation to texinfo

1 files changed, 119 insertions, 0 deletions

diff --git a/docs/gnulinux/grub_config.texi b/docs/gnulinux/grub_config.texi
new file mode 100644
index 00000000..458bcd89
--- /dev/null
+++ b/docs/gnulinux/grub_config.texi
@@ -0,0 +1,119 @@
+\input texinfo
+@documentencoding UTF-8
+
+@ifnottex
+@paragraphindent 0
+@end ifnottex
+@titlepage
+@title Writing a GRUB configuration file
+@end titlepage
+
+@node Top
+@top Writing a GRUB configuration file
+
+@menu
+* Writing a GRUB configuration file::
+* Table of Contents::
+@end menu
+
+@node Writing a GRUB configuration file
+@chapter Writing a GRUB configuration file
+@anchor{#writing-a-grub-configuration-file}
+This section is for those systems which use the GRUB payload. @strong{If your system uses the depthcharge payload, ignore this section.}
+
+@uref{index.html,Back to index}
+
+@node Table of Contents
+@chapter Table of Contents
+@anchor{#table-of-contents}
+@itemize
+@item
+@ref{#example_modifications,Example modifications for @emph{grubtest.cfg}}
+@itemize
+@item
+@ref{#example_modifications_trisquel,Trisquel GNU/Linux-libre}
+@item
+@ref{#example_modifications_parabola,Parabola GNU/Linux-libre}
+@end itemize
+
+@end itemize
+
+@menu
+* Example modifications for grubtestcfg::
+* Obvious option don't even modify the built-in grubcfg::
+* Trisquel with full disk encryption custom partition layout::
+@end menu
+
+@node Example modifications for grubtestcfg
+@section Example modifications for @emph{grubtest.cfg}
+@anchor{#example-modifications-for-grubtest.cfg}
+These are some common examples of ways in which the grubtest.cfg file can be modified.
+
+@node Obvious option don't even modify the built-in grubcfg
+@section Obvious option: don't even modify the built-in grub.cfg
+@anchor{#obvious-option-dont-even-modify-the-built-in-grub.cfg}
+Use the menuentry that says something like @emph{Search for GRUB outside CBFS}. Assuming that you have a grub.cfg file at /boot/grub/ in your installed distro, this will generate a new menuentry in the GRUB menu. Use that to boot.
+
+Then do this as root:@* $ @strong{cd /boot/grub/}@* $ @strong{ln -s grub.cfg libreboot_grub.cfg}
+
+After that, your system should then boot automatically.
+
+@node Trisquel with full disk encryption custom partition layout
+@section Trisquel with full disk encryption, custom partition layout
+@anchor{#trisquel-with-full-disk-encryption-custom-partition-layout}
+GRUB can boot from a symlink (or symlinks) pointing to your kernel/initramfs, whether from an unencrypted or encrypted /boot/. You can create your own custom symlink(s) but you have to manually update them when updating your kernel. This guide (not maintained by the libreboot project) shows how to configure Trisquel to automatically update that symlink on every kernel update. @uref{http://www.rel4tion.org/people/fr33domlover/libreboot-fix/,http://www.rel4tion.org/people/fr33domlover/libreboot-fix/}
+
+TODO: adapt those notes and put them here. The author said that it was CC-0, so re-licensing under GFDL shouldn't be a problem.
+@menu
+* Trisquel GNU/Linux-libre::
+* Parabola GNU/Linux-libre::
+@end menu
+
+@node Trisquel GNU/Linux-libre
+@subsection Trisquel GNU/Linux-libre
+@anchor{#trisquel-gnulinux-libre}
+As an example, on my test system in /boot/grub/grub.cfg (on the HDD/SSD) I see for the main menu entry:
+
+@itemize
+@item
+@strong{linux /boot/vmlinuz-3.15.1-gnu.nonpae root=UUID=3a008e14-4871-497b-95e5-fb180f277951 ro crashkernel=384M-2G:64M,2G-:128M quiet splash $vt_handoff}
+@item
+@strong{initrd /boot/initrd.img-3.15.1-gnu.nonpae}
+@end itemize
+
+@strong{ro}, @strong{quiet}, @strong{splash}, @strong{crashkernel=384M-2G:64M,2G-:128M} and @strong{$vt_handoff} can be safely ignored.
+
+I use this to get my partition layout:@* $ @strong{lsblk}
+
+In my case, I have no /boot partition, instead /boot is on the same partition as / on sda1. Yours might be different. In GRUB terms, sda means ahci0. 1 means msdos1, or gpt1, depending on whether I am using MBR or GPT partitioning. Thus, /dev/sda1 is GRUB is (ahci0,msdos1) or (ahci0,gpt1). In my case, I use MBR partitioning so it's (ahci0,msdos1). 'msdos' is a GRUB name simply because this partitioning type is traditionally used by MS-DOS. It doesn't mean that you have a proprietary OS.
+
+Trisquel doesn't keep the filenames of kernels consistent, instead it keeps old kernels and new kernel updates are provided with the version in the filename. This can make GRUB payload a bit tricky. Fortunately, there are symlinks /vmlinuz and /initrd.img so if your /boot and / are on the same partition, you can set GRUB to boot from that. These are also updated automatically when installing kernel updates from your distributions apt-get repositories. @strong{Note: when using @uref{http://jxself.org/linux-libre,jxself kernel releases}, these are not updated at all and you have to update them manually.}
+
+For the GRUB payload grubtest.cfg (in the 'Load Operating System' menu entry), we therefore have (in this example):@* @strong{set root='ahci0,msdos1'}@* @strong{linux /vmlinuz root=UUID=3a008e14-4871-497b-95e5-fb180f277951}@* @strong{initrd /initrd.img}
+
+Optionally, you can convert the UUID to its real device name, for example /dev/sda1 in this case. sdX naming isn't very reliable, though, which is why UUID is used for most distributions.
+
+Alternatively, if your /boot is on a separate partition then you cannot rely on the /vmlinuz and /initrd.img symlinks. Instead, go into /boot and create your own symlinks (update them manually when you install a new kernel update).@* $ @strong{sudo -s} (or @strong{su -})@* # @strong{cd /boot/}@* # @strong{rm -f vmlinuz initrd.img}@* # @strong{ln -s yourkernel ksym}@* # @strong{ln -s yourinitrd isym}@* # @strong{exit}
+
+Then your grubtest.cfg menu entry (for payload) becomes like that, for example if / was on sda2 and /boot was on sda1:@* @strong{set root='ahci0,msdos1'}@* @strong{linux /ksym root=/dev/sda2}@* @strong{initrd /isym}
+
+There are lots of possible variations so please try to adapt.
+
+@node Parabola GNU/Linux-libre
+@subsection Parabola GNU/Linux-libre
+@anchor{#parabola-gnulinux-libre}
+You can basically adapt the above. Note however that Parabola does not keep old kernels still installed, and the file names are always consistent, so you don't need to boot from symlinks, you can just use the real thing directly.
+
+@ref{#pagetop,Back to top of page.}
+
+Copyright © 2014, 2015 Francis Rowe <info@@gluglug.org.uk>@* Permission is granted to copy, distribute and/or modify this document under the terms of the GNU Free Documentation License, Version 1.3 or any later version published by the Free Software Foundation; with no Invariant Sections, no Front-Cover Texts, and no Back-Cover Texts. A copy of the license can be found at @uref{../gfdl-1.3.txt,../gfdl-1.3.txt}
+
+Updated versions of the license (when available) can be found at @uref{https://www.gnu.org/licenses/licenses.html,https://www.gnu.org/licenses/licenses.html}
+
+UNLESS OTHERWISE SEPARATELY UNDERTAKEN BY THE LICENSOR, TO THE EXTENT POSSIBLE, THE LICENSOR OFFERS THE LICENSED MATERIAL AS-IS AND AS-AVAILABLE, AND MAKES NO REPRESENTATIONS OR WARRANTIES OF ANY KIND CONCERNING THE LICENSED MATERIAL, WHETHER EXPRESS, IMPLIED, STATUTORY, OR OTHER. THIS INCLUDES, WITHOUT LIMITATION, WARRANTIES OF TITLE, MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE, NON-INFRINGEMENT, ABSENCE OF LATENT OR OTHER DEFECTS, ACCURACY, OR THE PRESENCE OR ABSENCE OF ERRORS, WHETHER OR NOT KNOWN OR DISCOVERABLE. WHERE DISCLAIMERS OF WARRANTIES ARE NOT ALLOWED IN FULL OR IN PART, THIS DISCLAIMER MAY NOT APPLY TO YOU.
+
+TO THE EXTENT POSSIBLE, IN NO EVENT WILL THE LICENSOR BE LIABLE TO YOU ON ANY LEGAL THEORY (INCLUDING, WITHOUT LIMITATION, NEGLIGENCE) OR OTHERWISE FOR ANY DIRECT, SPECIAL, INDIRECT, INCIDENTAL, CONSEQUENTIAL, PUNITIVE, EXEMPLARY, OR OTHER LOSSES, COSTS, EXPENSES, OR DAMAGES ARISING OUT OF THIS PUBLIC LICENSE OR USE OF THE LICENSED MATERIAL, EVEN IF THE LICENSOR HAS BEEN ADVISED OF THE POSSIBILITY OF SUCH LOSSES, COSTS, EXPENSES, OR DAMAGES. WHERE A LIMITATION OF LIABILITY IS NOT ALLOWED IN FULL OR IN PART, THIS LIMITATION MAY NOT APPLY TO YOU.
+
+The disclaimer of warranties and limitation of liability provided above shall be interpreted in a manner that, to the extent possible, most closely approximates an absolute disclaimer and waiver of all liability.
+
+@bye